@nanhara/hara 0.107.0 → 0.108.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to `@nanhara/hara`.
 > Versioning (pre-1.0, SemVer-style): the **minor** (middle) number bumps for a **new feature**; the
 > **patch** (last) number bumps for **optimizations/fixes of existing features**.
 
+## 0.108.0 — cron grows up: chat-native scheduling, delivery, a deterministic lane
+
+Distilled from a three-way study of openclaw (the production-grade scheduler running our company),
+hermes (the best creation UX), and hara's own minimal cron:
+
+- **`cronjob` model tool** (hermes parity): "every morning at 9, check X and send me a summary" in
+  chat just works — one action-style tool (add/list/remove/enable/disable/run), approval-gated like
+  any exec. **Recursion guard**: sessions spawned BY a cron job can't schedule more jobs.
+- **`--command` deterministic lane**: run the task as a plain shell command — no agent, no tokens,
+  exact exit codes. Fixed scripts stop burning an LLM round just to type `python script.py`.
+- **Result delivery** (openclaw/hermes parity): `--deliver telegram:<chatId> | feishu:<chatId> |
+  webhook:<url>` pushes each run's outcome (+ output tail) to a channel — no gateway process needed,
+  adapters fire one-shot from the same env vars.
+- **Failure alerts**: 3 consecutive failures (per-job `alertAfter`) → one 🚨 on the deliver channel,
+  6h cooldown, streak resets on success.
+- **Per-job timezone**: `--tz Asia/Shanghai` pins cron expressions to a wall clock (IANA, validated
+  at add time) instead of whatever the machine happens to be set to.
+
+Still the lightest of the three: no daemon — the OS (launchd/crontab) ticks `hara cron`.
+
 ## 0.107.0 — interjection triage: the model is the scheduler, the todo list is the queue
 
 - **Mid-task messages get triaged, not blindly folded in.** Typing while hara works always reached

package/README.md

@@ -8,7 +8,7 @@
 > with routing boundaries, a dispatcher, a single source-of-truth data layer, human-in-the-loop
 > approvals, and cron autonomy.
 
-🚧 **v0.89** · TypeScript · local-first · Apache-2.0
+[![npm](https://img.shields.io/npm/v/%40nanhara%2Fhara?label=npm&color=cb3837)](https://www.npmjs.com/package/@nanhara/hara) · TypeScript · local-first · Apache-2.0
 
 **Highlights**
 - **An org, not just an agent** — `hara org "<task>"` routes work to the role that *owns* it; `hara plan "<task>"` decomposes a task into a verified DAG of atoms (frame → atomize → sequence → execute → **verify gate**), and `hara plan --parallel` runs independent atoms concurrently.
@@ -17,6 +17,9 @@
 - **Persistent memory + self-evolution** — `memory_*` tools over global/project `MEMORY.md`; the agent recalls before acting, **proactively saves** durable facts, and grows its own playbooks (a lexical guard screens what it writes). Inspect/consolidate it with **`hara memory show`** and **`hara memory distill`** (promote recent daily logs → durable memory). Lexical-first by design — semantic search is opt-in, never required.
 - **Multi-provider, all streamed** — Anthropic (Claude) or any OpenAI-compatible endpoint (Qwen/DashScope, GLM, Kimi, OpenAI) with live Markdown + visible reasoning.
 - **Delegate to other agents** — the **`external_agent`** tool hands a self-contained task to **Claude Code** or **Codex** running headless, and returns the result — so you pick the best engine per task. Gated by approval, trust-tiered, and never exposed to read-only sub-agents.
+- **Honest under a slow network** — a live "waiting for the model… Ns" status, a stall watchdog that
+  auto-fails-over instead of hanging, big pastes folding to a token, and a startup update notice — the
+  terminal never feels dead.
 - **Solid coding core** — `edit_file` / `apply_patch` (atomic multi-file) with colored diffs · `grep`/`glob`/`ls`/`codebase_search` (lexical + optional semantic search over the repo) /`web_fetch` · fuzzy `@file` · `/undo` · `/compact` · **Esc-to-interrupt** · parallel sub-agents · MCP client · macOS sandbox.
 
 Track it: https://github.com/hara-cli/hara · https://hara.run

package/dist/cron/deliver.js

@@ -0,0 +1,59 @@
+// Cron result delivery — push a finished job's output to a chat channel (openclaw/hermes parity),
+// WITHOUT needing the gateway process: adapters are constructed one-shot from the same env vars the
+// gateway uses, send once, and are dropped. Spec format: "<target>:<id>" —
+//   telegram:<chatId>   (HARA_TELEGRAM_TOKEN)
+//   feishu:<chatId>     (HARA_FEISHU_APP_ID + HARA_FEISHU_APP_SECRET)
+//   webhook:<url>       (plain POST {name,status,text} JSON — for anything else)
+// WeChat is intentionally absent: its transport needs the long-lived gateway session, so a one-shot
+// cron process can't speak it — use feishu/telegram/webhook for cron delivery.
+// Adapters are imported LAZILY so the (heavy) SDKs never load unless a job actually delivers.
+/** Parse a `--deliver` spec; error string on anything unsupported (listing what IS supported). */
+export function parseDeliver(spec) {
+    const i = spec.indexOf(":");
+    if (i <= 0)
+        return { error: `bad deliver spec "${spec}" — use telegram:<chatId>, feishu:<chatId>, or webhook:<url>` };
+    const platform = spec.slice(0, i).toLowerCase();
+    const to = spec.slice(i + 1).trim();
+    if (!to)
+        return { error: `deliver spec "${spec}" is missing a target after ":"` };
+    if (platform === "telegram" || platform === "feishu" || platform === "webhook")
+        return { platform, to };
+    return { error: `unsupported deliver platform "${platform}" — supported: telegram, feishu, webhook (WeChat needs the live gateway)` };
+}
+/** Send `text` to the target. Returns null on success, or an error string (never throws — cron
+ *  delivery is best-effort and must not kill the tick). */
+export async function deliverResult(spec, text) {
+    const t = parseDeliver(spec);
+    if ("error" in t)
+        return t.error;
+    try {
+        if (t.platform === "webhook") {
+            const r = await fetch(t.to, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ source: "hara-cron", text }),
+                signal: AbortSignal.timeout(15_000),
+            });
+            return r.ok ? null : `webhook ${r.status}`;
+        }
+        if (t.platform === "telegram") {
+            const token = process.env.HARA_TELEGRAM_TOKEN;
+            if (!token)
+                return "HARA_TELEGRAM_TOKEN not set";
+            const { telegramAdapter } = await import("../gateway/telegram.js");
+            await telegramAdapter(token).send(t.to, text);
+            return null;
+        }
+        // feishu
+        const appId = process.env.HARA_FEISHU_APP_ID;
+        const appSecret = process.env.HARA_FEISHU_APP_SECRET;
+        if (!appId || !appSecret)
+            return "HARA_FEISHU_APP_ID / HARA_FEISHU_APP_SECRET not set";
+        const { feishuAdapter } = await import("../gateway/feishu.js");
+        await feishuAdapter(appId, appSecret).send(t.to, text);
+        return null;
+    }
+    catch (e) {
+        return `delivery failed: ${e instanceof Error ? e.message : String(e)}`;
+    }
+}

package/dist/cron/runner.js

@@ -2,9 +2,10 @@
 // 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 { deliverResult } from "./deliver.js";
 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 { loadJobs, recordRun, recordAlert, findJob, 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) {
@@ -39,7 +40,6 @@ function capLog(log) {
 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 {
@@ -48,9 +48,17 @@ export function runJobOnce(job) {
         catch {
             /* logging is best-effort */
         }
+        // mode "command" = the deterministic lane (hermes-style): run the task as a plain shell command —
+        // no agent, no tokens, exact. The other modes spawn a fresh hara session. Either way HARA_CRON=1
+        // marks the child so cron-run sessions can't create more cron jobs (recursion guard).
         const self = selfArgv();
-        const child = spawn(self[0], [...self.slice(1), ...args], { cwd: job.cwd, env: process.env });
+        const [cmd, argv] = job.mode === "command"
+            ? ["bash", ["-lc", job.task]]
+            : [self[0], [...self.slice(1), ...(job.mode === "org" ? ["org", job.task] : ["-p", job.task, "--approval", "full-auto"])]];
+        const child = spawn(cmd, argv, { cwd: job.cwd, env: { ...process.env, HARA_CRON: "1" } });
+        let tail = ""; // last few KB, for chat delivery (the full stream goes to the log file)
         const append = (d) => {
+            tail = (tail + d.toString()).slice(-4_000);
             try {
                 appendFileSync(log, d);
             }
@@ -60,10 +68,38 @@ export function runJobOnce(job) {
         };
         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}` }));
+        child.on("error", (e) => resolve({ ok: false, error: String(e?.message ?? e), output: tail }));
+        child.on("close", (code) => resolve(code === 0 ? { ok: true, output: tail } : { ok: false, error: `exited ${code}`, output: tail }));
     });
 }
+/** After a run: push the outcome to the job's deliver channel, and — on repeated failures — a 🚨 alert
+ *  (threshold `alertAfter` (default 3), 6h cooldown). Best-effort: a delivery error only hits the log.
+ *  `deliver` + `nowMs` injectable for tests. */
+export async function deliverOutcome(job, r, deliver = deliverResult, nowMs = Date.now()) {
+    if (!job.deliver)
+        return;
+    const snippet = (r.output ?? "").trim().slice(-1_500);
+    const head = r.ok ? `⏰ ${job.name} ✓` : `⏰ ${job.name} ✗ ${r.error ?? "failed"}`;
+    const err = await deliver(job.deliver, snippet ? `${head}\n${snippet}` : head);
+    if (err) {
+        try {
+            appendFileSync(logPath(job.id), `\n[deliver] ${err}\n`);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    if (!r.ok) {
+        const fresh = findJob(job.id); // recordRun already bumped consecutiveErrors
+        const count = fresh?.consecutiveErrors ?? 0;
+        const threshold = job.alertAfter ?? 3;
+        const cooled = !fresh?.lastAlertAt || nowMs - fresh.lastAlertAt > 6 * 3_600_000;
+        if (count >= threshold && cooled) {
+            await deliver(job.deliver, `🚨 ${job.name} has failed ${count}× in a row — latest: ${r.error ?? "unknown"}. Log: ${logPath(job.id)}`);
+            recordAlert(job.id, nowMs);
+        }
+    }
+}
 /** 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. */
@@ -97,6 +133,7 @@ export async function runTick(nowMs, run = runJobOnce) {
         for (const job of due) {
             const r = await run(job);
             recordRun(job.id, nowMs, r.ok ? "ok" : "error", r.error);
+            await deliverOutcome(job, r);
             ran.push(job.id);
         }
         return { ran };

package/dist/cron/schedule.js

@@ -67,15 +67,56 @@ export function parseCron(expr) {
         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) {
+/** Offset (ms) of IANA zone `tz` from UTC at instant `atMs`. Cached per (tz, hour) — offsets only move
+ *  at DST transitions, so hour-bucket caching keeps nextRun's minute-by-minute scan fast. */
+const offsetCache = new Map();
+export function zoneOffsetMs(tz, atMs) {
+    const key = `${tz}:${Math.floor(atMs / 3_600_000)}`;
+    const hit = offsetCache.get(key);
+    if (hit !== undefined)
+        return hit;
+    const fmt = new Intl.DateTimeFormat("en-US", {
+        timeZone: tz,
+        year: "numeric", month: "2-digit", day: "2-digit",
+        hour: "2-digit", minute: "2-digit", second: "2-digit", hour12: false,
+    });
+    const p = {};
+    for (const part of fmt.formatToParts(new Date(atMs)))
+        p[part.type] = part.value;
+    const asUtc = Date.UTC(Number(p.year), Number(p.month) - 1, Number(p.day), Number(p.hour) % 24, Number(p.minute), Number(p.second));
+    const off = asUtc - Math.floor(atMs / 1000) * 1000;
+    if (offsetCache.size > 10_000)
+        offsetCache.clear();
+    offsetCache.set(key, off);
+    return off;
+}
+/** Is `tz` a valid IANA timezone? (validated at job-add time so a typo fails loudly, not silently-local) */
+export function validTz(tz) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: tz });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Wall-clock parts of the instant — in `tz` when given (offset-shifted UTC getters), else local. */
+function wallParts(d, tz) {
+    if (!tz)
+        return { min: d.getMinutes(), hour: d.getHours(), dom: d.getDate(), mon: d.getMonth() + 1, dow: d.getDay() };
+    const z = new Date(d.getTime() + zoneOffsetMs(tz, d.getTime()));
+    return { min: z.getUTCMinutes(), hour: z.getUTCHours(), dom: z.getUTCDate(), mon: z.getUTCMonth() + 1, dow: z.getUTCDay() };
+}
+/** Does `expr` fire at the given minute (in `tz` when set, else local)? Vixie dom/dow OR rule. */
+export function cronMatches(expr, d, tz) {
     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))
+    const w = wallParts(d, tz);
+    if (!p.m.has(w.min) || !p.h.has(w.hour) || !p.mon.has(w.mon))
         return false;
-    const domOk = p.dom.has(d.getDate());
-    const dowOk = p.dow.has(d.getDay());
+    const domOk = p.dom.has(w.dom);
+    const dowOk = p.dow.has(w.dow);
     if (p.domStar && p.dowStar)
         return true; // both unrestricted → any day
     if (!p.domStar && !p.dowStar)
@@ -117,7 +158,7 @@ export function describeSchedule(sched) {
 export function isDue(job, nowMs) {
     const s = job.schedule;
     if (s.kind === "cron") {
-        if (!cronMatches(s.expr, new Date(nowMs)))
+        if (!cronMatches(s.expr, new Date(nowMs), job.tz))
             return false;
         return job.lastRunAt === undefined || Math.floor(job.lastRunAt / 60_000) < Math.floor(nowMs / 60_000);
     }
@@ -140,7 +181,7 @@ export function nextRun(job, fromMs) {
         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)))
+        if (cronMatches(s.expr, new Date(t), job.tz))
             return t;
     }
     return null;

package/dist/cron/store.js

@@ -83,5 +83,15 @@ export function recordRun(id, at, status, error) {
     job.lastRunAt = at;
     job.lastStatus = status;
     job.lastError = error;
+    job.consecutiveErrors = status === "error" ? (job.consecutiveErrors ?? 0) + 1 : 0;
+    saveJobs(jobs);
+}
+/** Stamp the failure-alert time (cooldown gate). */
+export function recordAlert(id, at) {
+    const jobs = loadJobs();
+    const job = jobs.find((x) => x.id === id);
+    if (!job)
+        return;
+    job.lastAlertAt = at;
     saveJobs(jobs);
 }

package/dist/index.js

@@ -33,7 +33,8 @@ import { userTurnPreviews, rewindTo } from "./agent/rewind.js";
 import { checkpoint, listCheckpoints, restoreCheckpoint } from "./checkpoints.js";
 import { mapLimit, maxParallel } from "./concurrency.js";
 import { parseVerdict, captureChanges, reviewPrompt, fixPrompt, REVIEWER_SYSTEM, isTreeClean, stripCommitFence } from "./org/review-chain.js";
-import { parseSchedule, describeSchedule, nextRun } from "./cron/schedule.js";
+import { parseSchedule, describeSchedule, nextRun, validTz } from "./cron/schedule.js";
+import { parseDeliver } from "./cron/deliver.js";
 import { addJob, removeJob, setEnabled, resolveJob, loadJobs, recordRun, logPath } from "./cron/store.js";
 import { runTick, runJobOnce, selfArgv } from "./cron/runner.js";
 import { installScheduler, uninstallScheduler, isInstalled } from "./cron/install.js";
@@ -74,6 +75,7 @@ import "./tools/todo.js"; // register todo_write (inline task checklist)
 import "./tools/send.js"; // register send_file (self-gates on HARA_GATEWAY — pushes a file to the chat)
 import "./tools/external_agent.js"; // register external_agent (delegate to claude-code / codex headless)
 import "./tools/ask_user.js"; // register ask_user (pause mid-turn to ask the user a structured question)
+import "./tools/cron.js"; // register cronjob (model-facing scheduler — "remind me every morning" just works)
 import { computerBackends } from "./tools/computer.js"; // register the computer tool + expose the backend probe
 const here = dirname(fileURLToPath(import.meta.url));
 // Version: from a build-time define in the compiled single-binary (no package.json on its virtual FS),
@@ -1737,13 +1739,37 @@ cronCmd
     .description('schedule a task — schedule = cron expr ("0 9 * * *"), "every 30m", "in 2h", or an ISO timestamp')
     .option("--name <name>", "a label for the job")
     .option("--org", "run via `hara org` (role routing + review) instead of a plain `hara -p` prompt")
+    .option("--command", "run the task as a plain SHELL COMMAND — deterministic, no agent, no tokens")
+    .option("--tz <zone>", 'IANA timezone for cron exprs (e.g. "Asia/Shanghai"); default = local time')
+    .option("--deliver <spec>", "push each run's result: telegram:<chatId> | feishu:<chatId> | webhook:<url>")
     .action((schedule, taskParts, opts) => {
     const task = taskParts.join(" ");
+    if (opts.org && opts.command)
+        return void out(c.red("--org and --command are mutually exclusive\n"));
     const sched = parseSchedule(schedule, Date.now());
     if ("error" in sched)
         return void out(c.red(sched.error + "\n"));
-    const job = addJob({ name: opts.name || task.slice(0, 48), schedule: sched, task, mode: opts.org ? "org" : "print", cwd: process.cwd(), createdAt: Date.now() });
-    out(c.green(`✓ scheduled ${job.id}`) + c.dim(` · ${describeSchedule(sched)} · ${job.mode} · cwd ${job.cwd}\n`));
+    if (opts.tz && !validTz(opts.tz))
+        return void out(c.red(`invalid timezone "${opts.tz}" (IANA name, e.g. Asia/Shanghai)\n`));
+    if (opts.tz && sched.kind !== "cron")
+        return void out(c.red("--tz only applies to cron expressions\n"));
+    if (opts.deliver) {
+        const d = parseDeliver(opts.deliver);
+        if ("error" in d)
+            return void out(c.red(d.error + "\n"));
+    }
+    const mode = opts.command ? "command" : opts.org ? "org" : "print";
+    const job = addJob({
+        name: opts.name || task.slice(0, 48),
+        schedule: sched,
+        task,
+        mode,
+        cwd: process.cwd(),
+        ...(opts.tz ? { tz: opts.tz } : {}),
+        ...(opts.deliver ? { deliver: opts.deliver } : {}),
+        createdAt: Date.now(),
+    });
+    out(c.green(`✓ scheduled ${job.id}`) + c.dim(` · ${describeSchedule(sched)}${opts.tz ? ` @ ${opts.tz}` : ""} · ${job.mode}${opts.deliver ? ` · → ${opts.deliver}` : ""} · cwd ${job.cwd}\n`));
     if (!isInstalled())
         out(c.yellow("⚠ scheduler not installed yet — run `hara cron install` so jobs actually fire.\n"));
 });

package/dist/tools/cron.js

@@ -0,0 +1,107 @@
+// cronjob — the model-facing scheduler tool (hermes parity): "remind me every morning at 9" in chat
+// just works, no CLI knowledge needed. One action-style tool (add/list/remove/enable/disable/run)
+// instead of six. kind:"exec" so creating/removing jobs rides the normal approval gate.
+//
+// Recursion guard (hermes's rule): a session SPAWNED BY a cron job runs with HARA_CRON=1 and is
+// refused here — a scheduled task must never schedule more tasks, or one bad prompt snowballs.
+import { registerTool } from "./registry.js";
+import { addJob, loadJobs, resolveJob, removeJob, setEnabled } from "../cron/store.js";
+import { parseSchedule, describeSchedule, nextRun, validTz } from "../cron/schedule.js";
+import { runJobOnce } from "../cron/runner.js";
+import { parseDeliver } from "../cron/deliver.js";
+import { isInstalled } from "../cron/install.js";
+const fmt = (ms) => (ms ? new Date(ms).toLocaleString() : "—");
+registerTool({
+    name: "cronjob",
+    description: "Manage the user's scheduled jobs (hara cron). Use when they ask to schedule, automate, or be reminded of " +
+        "something on a time basis. action=add needs `schedule` (cron expr \"0 9 * * *\" · \"every 30m\" · \"in 2h\" · ISO time) " +
+        "and `task`. Optional: `name`; `mode` — \"print\" (default: run task as a hara prompt), \"org\" (role-routed), or " +
+        "\"command\" (run task as a plain SHELL COMMAND — deterministic, no agent, no tokens; prefer it for fixed scripts); " +
+        "`tz` (IANA, e.g. Asia/Shanghai, for cron exprs); `deliver` (push each run's result: telegram:<chatId> | " +
+        "feishu:<chatId> | webhook:<url>). Other actions: list · remove · enable · disable · run (fire now), with `id`. " +
+        "Jobs fire via the OS scheduler even when hara isn't running.",
+    input_schema: {
+        type: "object",
+        properties: {
+            action: { type: "string", enum: ["add", "list", "remove", "enable", "disable", "run"] },
+            schedule: { type: "string", description: "for add" },
+            task: { type: "string", description: "for add — the prompt / org task / shell command" },
+            name: { type: "string" },
+            mode: { type: "string", enum: ["print", "org", "command"] },
+            tz: { type: "string", description: "IANA timezone for cron exprs" },
+            deliver: { type: "string", description: "telegram:<chatId> | feishu:<chatId> | webhook:<url>" },
+            id: { type: "string", description: "job id (or unique prefix) for remove/enable/disable/run" },
+        },
+        required: ["action"],
+    },
+    kind: "exec", // scheduling machinery on the user's machine — approval-gated like any exec
+    async run(input, ctx) {
+        if (process.env.HARA_CRON === "1")
+            return "Error: cron-run sessions cannot manage cron jobs (recursion guard — a scheduled task must not schedule more tasks).";
+        const action = String(input.action ?? "");
+        if (action === "list") {
+            const jobs = loadJobs();
+            if (!jobs.length)
+                return "No scheduled jobs.";
+            return jobs
+                .map((j) => {
+                const next = nextRun(j, Date.now());
+                return `${j.id} · ${j.enabled ? "on " : "OFF"} · ${j.name} · ${describeSchedule(j.schedule)}${j.tz ? ` @ ${j.tz}` : ""} · mode ${j.mode}${j.deliver ? ` · → ${j.deliver}` : ""} · next ${fmt(next)} · last ${j.lastStatus ?? "—"}${j.consecutiveErrors ? ` (${j.consecutiveErrors}✗)` : ""}`;
+            })
+                .join("\n");
+        }
+        if (action === "add") {
+            const scheduleStr = String(input.schedule ?? "").trim();
+            const task = String(input.task ?? "").trim();
+            if (!scheduleStr || !task)
+                return "Error: add needs `schedule` and `task`.";
+            const sched = parseSchedule(scheduleStr, Date.now());
+            if ("error" in sched)
+                return `Error: ${sched.error}`;
+            const tz = input.tz ? String(input.tz) : undefined;
+            if (tz && !validTz(tz))
+                return `Error: invalid timezone "${tz}" (IANA name, e.g. Asia/Shanghai).`;
+            if (tz && sched.kind !== "cron")
+                return "Error: `tz` only applies to cron expressions.";
+            const deliver = input.deliver ? String(input.deliver) : undefined;
+            if (deliver) {
+                const d = parseDeliver(deliver);
+                if ("error" in d)
+                    return `Error: ${d.error}`;
+            }
+            const mode = input.mode === "org" || input.mode === "command" ? input.mode : "print";
+            const job = addJob({
+                name: input.name ? String(input.name) : task.slice(0, 48),
+                schedule: sched,
+                task,
+                mode,
+                cwd: ctx.cwd,
+                ...(tz ? { tz } : {}),
+                ...(deliver ? { deliver } : {}),
+                createdAt: Date.now(),
+            });
+            const warn = isInstalled() ? "" : "\n⚠ The OS scheduler isn't installed yet — tell the user to run `hara cron install` once, or jobs won't fire.";
+            return `✓ scheduled ${job.id} · ${describeSchedule(sched)}${tz ? ` @ ${tz}` : ""} · mode ${mode}${deliver ? ` · → ${deliver}` : ""} · next ${fmt(nextRun(job, Date.now()))}${warn}`;
+        }
+        // id-based actions
+        const idArg = String(input.id ?? "").trim();
+        if (!idArg)
+            return `Error: ${action} needs \`id\`.`;
+        const j = resolveJob(idArg);
+        if (j === "ambiguous")
+            return `Error: id "${idArg}" matches multiple jobs — use more characters.`;
+        if (!j)
+            return `Error: no job matching "${idArg}".`;
+        if (action === "remove")
+            return removeJob(j.id) ? `✓ removed ${j.id} (${j.name})` : "Error: remove failed.";
+        if (action === "enable" || action === "disable") {
+            setEnabled(j.id, action === "enable");
+            return `✓ ${j.id} ${action}d`;
+        }
+        if (action === "run") {
+            const r = await runJobOnce(j);
+            return r.ok ? `✓ ran ${j.id} — ok\n${(r.output ?? "").trim().slice(-800)}` : `✗ ${j.id} failed: ${r.error}\n${(r.output ?? "").trim().slice(-800)}`;
+        }
+        return `Error: unknown action "${action}".`;
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.107.0",
+  "version": "0.108.0",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "dist/index.js"