@oharness/engine 0.5.1 → 0.7.0

package/dist/schedule/lock.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Who on this machine fires routines.
+ *
+ * Every copy of the harness that watches the clock reads the same user config,
+ * so without this a routine fires once per copy: the desktop app and a
+ * `schedule daemon` left running in a terminal would both summarise yesterday's
+ * commits at nine. One holder at a time; the others keep asking, so when the
+ * holder quits the next one takes over within a tick instead of routines going
+ * quiet until a restart.
+ *
+ * A file with a pid rather than an OS lock: node has no portable advisory
+ * lock, and a pid that is no longer alive is a lock nobody holds — which is
+ * what a crashed holder leaves behind.
+ */
+export declare class RoutineLock {
+    private readonly file;
+    private held;
+    constructor(file?: string);
+    /**
+     * Claim a minute: true when this process holds the lock and nobody has
+     * handled that minute yet, taking the lock if it is free.
+     *
+     * The minute is written into the lock, not kept in memory, because the
+     * dangerous moment is a takeover: a holder that quits after firing at 9:00
+     * leaves the file behind, and the next process to look — still inside 9:00
+     * — would otherwise fire everything a second time.
+     */
+    claim(minute: number): Promise<boolean>;
+    /**
+     * Give the lock up, if this process has it.
+     *
+     * The file stays, owned by nobody, because the minute in it is still true:
+     * quitting just after firing at 9:00 must not let whoever takes over next
+     * fire 9:00 again.
+     */
+    release(): Promise<void>;
+    private read;
+}

package/dist/schedule/lock.js

@@ -0,0 +1,100 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { userPath } from "../paths.js";
+import { parseJson } from "../util/json.js";
+/**
+ * Who on this machine fires routines.
+ *
+ * Every copy of the harness that watches the clock reads the same user config,
+ * so without this a routine fires once per copy: the desktop app and a
+ * `schedule daemon` left running in a terminal would both summarise yesterday's
+ * commits at nine. One holder at a time; the others keep asking, so when the
+ * holder quits the next one takes over within a tick instead of routines going
+ * quiet until a restart.
+ *
+ * A file with a pid rather than an OS lock: node has no portable advisory
+ * lock, and a pid that is no longer alive is a lock nobody holds — which is
+ * what a crashed holder leaves behind.
+ */
+export class RoutineLock {
+    file;
+    held = false;
+    constructor(file = userPath("schedules", "clock.lock")) {
+        this.file = file;
+    }
+    /**
+     * Claim a minute: true when this process holds the lock and nobody has
+     * handled that minute yet, taking the lock if it is free.
+     *
+     * The minute is written into the lock, not kept in memory, because the
+     * dangerous moment is a takeover: a holder that quits after firing at 9:00
+     * leaves the file behind, and the next process to look — still inside 9:00
+     * — would otherwise fire everything a second time.
+     */
+    async claim(minute) {
+        const current = await this.read();
+        const mine = current?.pid === process.pid;
+        if (!mine && current && alive(current.pid))
+            return (this.held = false);
+        const done = current?.minute ?? -1;
+        await mkdir(path.dirname(this.file), { recursive: true });
+        try {
+            // `wx` when nobody has ever held it, so two processes starting at once
+            // cannot both create it; a stale file, or our own, is replaced.
+            await writeFile(this.file, JSON.stringify({ pid: process.pid, since: mine ? current.since : Date.now(), minute: Math.max(done, minute) }), { flag: current ? "w" : "wx" });
+        }
+        catch {
+            return (this.held = false);
+        }
+        // Read back: two processes replacing the same stale file both succeed, and
+        // the one whose pid is in it now is the one that won.
+        this.held = (await this.read())?.pid === process.pid;
+        return this.held && minute > done;
+    }
+    /**
+     * Give the lock up, if this process has it.
+     *
+     * The file stays, owned by nobody, because the minute in it is still true:
+     * quitting just after firing at 9:00 must not let whoever takes over next
+     * fire 9:00 again.
+     */
+    async release() {
+        if (!this.held)
+            return;
+        this.held = false;
+        const current = await this.read();
+        if (current?.pid !== process.pid)
+            return;
+        await writeFile(this.file, JSON.stringify({ pid: 0, since: 0, minute: current.minute ?? -1 }));
+    }
+    async read() {
+        let raw;
+        try {
+            raw = await readFile(this.file, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+        const parsed = parseJson(raw);
+        const value = parsed.ok && parsed.value && typeof parsed.value === "object" ? parsed.value : {};
+        // An unreadable file is held by nobody; 0 is never a live pid.
+        return {
+            pid: typeof value.pid === "number" ? value.pid : 0,
+            since: typeof value.since === "number" ? value.since : 0,
+            ...(typeof value.minute === "number" ? { minute: value.minute } : {}),
+        };
+    }
+}
+function alive(pid) {
+    if (pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM: it exists and belongs to someone else. Still alive.
+        return err.code === "EPERM";
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/schedule/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/schedule/lock.ts"],"names":[],"mappings":"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"}

package/dist/schedule/runner.d.ts

@@ -0,0 +1,67 @@
+import type { Harness } from "../harness.ts";
+import type { Logger } from "../util/logger.ts";
+import type { ClockRoutine } from "./clock.ts";
+import type { RoutineLock } from "./lock.ts";
+import type { ScheduleRun } from "./scheduler.ts";
+export interface RoutineRunnerOptions {
+    /** Where a routine written by hand without a directory runs. */
+    defaultCwd: string;
+    /** The projects open in this process, whose harnesses a run can reuse. */
+    openHarnesses(): Iterable<Harness>;
+    /** Make a harness for a project that is not open. Closed with the runner. */
+    createHarness(cwd: string): Promise<Harness>;
+    onStart?(routine: ClockRoutine, meta: {
+        scheduledFor: number;
+        catchUp: boolean;
+    }): void;
+    onRun?(run: ScheduleRun, routine: ClockRoutine): void;
+    onError?(routine: ClockRoutine, error: string): void;
+    logger?: Logger;
+    lock?: RoutineLock;
+}
+/**
+ * Routines for one process: which exist, where each runs, and the clock that
+ * fires them.
+ *
+ * Shared by the desktop app's server, the TUI and `schedule daemon`, so all
+ * three agree on the two things that were each getting wrong on their own —
+ * that a routine runs in the project it names, not the one the process
+ * happened to start in, and that only one process on the machine fires them.
+ */
+export declare class RoutineRunner {
+    private readonly opts;
+    private readonly own;
+    private clock?;
+    constructor(opts: RoutineRunnerOptions);
+    /**
+     * Every routine that could fire, and the directory each runs in.
+     *
+     * The user's own name their directory. A project's oharness.config.json
+     * contributes its routines while that project is open in this process, and
+     * wins a name it shares with the user's in the same directory, as it does
+     * when the config is loaded.
+     */
+    list(): Promise<ClockRoutine[]>;
+    /** A routine by name, preferring the one in `cwd` when two share it. */
+    find(name: string, cwd?: string): Promise<ClockRoutine | undefined>;
+    /**
+     * Run one in its own project. Undefined when that project is already
+     * running it. With no meta it is a run by hand, which answers no scheduled
+     * time.
+     */
+    run(routine: ClockRoutine, meta?: {
+        scheduledFor?: number;
+        catchUp?: boolean;
+    }): Promise<ScheduleRun | undefined>;
+    /** Start firing on schedule. */
+    start(): void;
+    close(): Promise<void>;
+    /**
+     * An open project's harness, or one of the runner's own.
+     *
+     * Kept apart from the ones the user switches between: a routine firing is
+     * not the user opening a project, and must not add it to their list or make
+     * it what the next launch opens.
+     */
+    private harnessFor;
+}

package/dist/schedule/runner.js

@@ -0,0 +1,100 @@
+import { loadProjectConfig, loadUserConfig } from "../config.js";
+import { RoutineClock } from "./clock.js";
+/**
+ * Routines for one process: which exist, where each runs, and the clock that
+ * fires them.
+ *
+ * Shared by the desktop app's server, the TUI and `schedule daemon`, so all
+ * three agree on the two things that were each getting wrong on their own —
+ * that a routine runs in the project it names, not the one the process
+ * happened to start in, and that only one process on the machine fires them.
+ */
+export class RoutineRunner {
+    opts;
+    own = new Map();
+    clock;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * Every routine that could fire, and the directory each runs in.
+     *
+     * The user's own name their directory. A project's oharness.config.json
+     * contributes its routines while that project is open in this process, and
+     * wins a name it shares with the user's in the same directory, as it does
+     * when the config is loaded.
+     */
+    async list() {
+        const found = new Map();
+        const user = await loadUserConfig().catch(() => ({ schedules: [] }));
+        for (const def of user.schedules ?? []) {
+            const cwd = def.cwd ?? this.opts.defaultCwd;
+            found.set(def.name + "\0" + cwd, { def, cwd });
+        }
+        for (const harness of this.opts.openHarnesses()) {
+            const project = await loadProjectConfig(harness.cwd).catch(() => undefined);
+            for (const def of project?.schedules ?? []) {
+                found.set(def.name + "\0" + harness.cwd, { def, cwd: harness.cwd });
+            }
+        }
+        return [...found.values()];
+    }
+    /** A routine by name, preferring the one in `cwd` when two share it. */
+    async find(name, cwd) {
+        const candidates = (await this.list()).filter((one) => one.def.name === name);
+        return candidates.find((one) => one.cwd === cwd) ?? candidates[0];
+    }
+    /**
+     * Run one in its own project. Undefined when that project is already
+     * running it. With no meta it is a run by hand, which answers no scheduled
+     * time.
+     */
+    async run(routine, meta = {}) {
+        const harness = await this.harnessFor(routine.cwd);
+        return harness.scheduler.runDefinition(routine.def, meta);
+    }
+    /** Start firing on schedule. */
+    start() {
+        if (this.clock)
+            return;
+        this.clock = new RoutineClock({
+            routines: () => this.list(),
+            run: (routine, meta) => this.run(routine, meta),
+            ...(this.opts.onStart ? { onStart: this.opts.onStart } : {}),
+            ...(this.opts.onRun ? { onRun: this.opts.onRun } : {}),
+            ...(this.opts.onError ? { onError: this.opts.onError } : {}),
+            ...(this.opts.logger ? { logger: this.opts.logger } : {}),
+            ...(this.opts.lock ? { lock: this.opts.lock } : {}),
+        });
+        this.clock.start();
+    }
+    async close() {
+        await this.clock?.stop();
+        this.clock = undefined;
+        for (const pending of this.own.values()) {
+            await pending.then((harness) => harness.close()).catch(() => { });
+        }
+        this.own.clear();
+    }
+    /**
+     * An open project's harness, or one of the runner's own.
+     *
+     * Kept apart from the ones the user switches between: a routine firing is
+     * not the user opening a project, and must not add it to their list or make
+     * it what the next launch opens.
+     */
+    harnessFor(cwd) {
+        for (const harness of this.opts.openHarnesses()) {
+            if (harness.cwd === cwd)
+                return Promise.resolve(harness);
+        }
+        let pending = this.own.get(cwd);
+        if (!pending) {
+            pending = this.opts.createHarness(cwd);
+            this.own.set(cwd, pending);
+            pending.catch(() => this.own.delete(cwd));
+        }
+        return pending;
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/schedule/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/schedule/runner.ts"],"names":[],"mappings":"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"}

package/dist/schedule/scheduler.d.ts

@@ -1,3 +1,4 @@
+import type { CronFields } from "./cron.ts";
 import type { Harness } from "../harness.ts";
 import type { PermissionMode } from "../agent/permissions.ts";
 export interface ScheduleDefinition {
@@ -14,10 +15,21 @@ export interface ScheduleDefinition {
      */
     permissionMode?: PermissionMode;
     maxTurns?: number;
+    /** False pauses it: kept, listed, never fired. */
     enabled?: boolean;
     /** Working directory for the run; defaults to the harness cwd. */
     cwd?: string;
+    /**
+     * When it was made. A routine is never caught up for a time before it
+     * existed; one written by hand without this is caught up only from the
+     * first time a clock saw it.
+     */
+    createdAt?: number;
 }
+/**
+ * One line of a routine's history: a run, or a scheduled time that was
+ * deliberately not run.
+ */
 export interface ScheduleRun {
     schedule: string;
     startedAt: number;
@@ -29,19 +41,45 @@ export interface ScheduleRun {
     /** Final assistant text, truncated. */
     output: string;
     error?: string;
+    /**
+     * The scheduled time this answered, before any stagger. Absent on a run
+     * started by hand — which is why a manual run never stands in for the
+     * scheduled one after it.
+     */
+    scheduledFor?: number;
+    /** Started late, because the scheduled time passed while nothing was watching. */
+    catchUp?: boolean;
+    /** Not run at all; `reason` says why. */
+    skipped?: boolean;
+    reason?: "still-running";
 }
 export interface ScheduleStatus {
     name: string;
     cron: string;
     enabled: boolean;
     nextRunAt?: number;
+    /** The last run that actually ran — a skipped time is history, not a result. */
     lastRun?: ScheduleRun;
 }
 /**
- * Runs prompts on a cron schedule.
+ * Minutes a routine starts after its scheduled time, the same every time for
+ * the same routine.
+ *
+ * "Every day at 9" is what most people write, and every copy firing at 9:00:00
+ * is a queue at the gateway at 9:00:00. A few minutes, fixed by the name so a
+ * routine keeps its own slot rather than wandering, and none at all for one
+ * that fires more than once an hour, where a few minutes is most of its
+ * interval.
+ */
+export declare function staggerMinutes(def: Pick<ScheduleDefinition, "name">, fields: CronFields): number;
+/**
+ * Holds routines, runs them, and keeps their history.
+ *
+ * It does not watch the clock: RoutineClock does, for every project at once,
+ * and asks the scheduler of each routine's own project to run it.
  *
- * Each firing gets its own session rather than appending to a long-lived one:
- * a nightly job that shares context with every previous night would compact
+ * Each run gets its own session rather than appending to a long-lived one: a
+ * nightly job that shares context with every previous night would compact
  * itself into uselessness within a week, and a failure would poison every
  * subsequent run.
  */
@@ -50,8 +88,6 @@ export declare class Scheduler {
     private readonly logger;
     private readonly schedules;
     private readonly runDir;
-    private timer?;
-    private running;
     /** Names currently executing, so a slow job cannot overlap itself. */
     private readonly inFlight;
     constructor(harness: Harness, definitions?: ScheduleDefinition[], opts?: {
@@ -69,19 +105,24 @@ export declare class Scheduler {
      */
     runNow(name: string): Promise<ScheduleRun>;
     /**
-     * Start firing on schedule.
+     * Run a definition in this harness, whether or not this scheduler holds it.
      *
-     * Wakes every 30s and fires anything whose minute has arrived, rather than
-     * sleeping until the exact next occurrence: a laptop that suspends would
-     * otherwise wake with a timer scheduled for a moment that has passed.
+     * For the clock, which watches routines across projects: it decides what is
+     * due, and each routine runs in the harness of the directory it names — the
+     * project's instructions, MCP servers and permission rules — rather than in
+     * whichever project happened to notice the minute arrive.
      */
-    start(): void;
-    stop(): void;
-    /** Resolves when every in-flight run has finished. */
-    drain(): Promise<void>;
+    runDefinition(def: ScheduleDefinition, meta?: {
+        scheduledFor?: number;
+        catchUp?: boolean;
+    }): Promise<ScheduleRun | undefined>;
+    isRunning(name: string): boolean;
     private execute;
-    private recordRun;
     private lastRun;
-    /** Past runs, newest first. */
+    /** Past runs and skipped times, newest first. */
     history(name: string, limit?: number): Promise<ScheduleRun[]>;
 }
+/** Add one line to a routine's history. */
+export declare function appendRun(runDir: string, run: ScheduleRun): Promise<void>;
+/** A routine's history, oldest first. Lines that do not parse are passed over. */
+export declare function readRuns(runDir: string, name: string): Promise<ScheduleRun[]>;