@oharness/engine 0.1.0

package/dist/schedule/cron.js

@@ -0,0 +1,125 @@
+import { ConfigError } from "../core/errors.js";
+const ALIASES = {
+    "@yearly": "0 0 1 1 *",
+    "@annually": "0 0 1 1 *",
+    "@monthly": "0 0 1 * *",
+    "@weekly": "0 0 * * 0",
+    "@daily": "0 0 * * *",
+    "@midnight": "0 0 * * *",
+    "@hourly": "0 * * * *",
+};
+const MONTH_NAMES = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+const DAY_NAMES = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+const SPECS = [
+    { min: 0, max: 59 },
+    { min: 0, max: 23 },
+    { min: 1, max: 31 },
+    { min: 1, max: 12, names: MONTH_NAMES },
+    { min: 0, max: 7, names: DAY_NAMES },
+];
+export function parseCron(expression) {
+    const normalized = ALIASES[expression.trim().toLowerCase()] ?? expression.trim();
+    const parts = normalized.split(/\s+/);
+    if (parts.length !== 5) {
+        throw new ConfigError(`cron expression must have 5 fields (minute hour day-of-month month day-of-week), got ${parts.length}: "${expression}"`);
+    }
+    const sets = parts.map((part, index) => parseField(part, SPECS[index], expression));
+    // Cron writes Sunday as either 0 or 7; normalize so lookups only check 0.
+    const dayOfWeek = sets[4];
+    if (dayOfWeek.has(7)) {
+        dayOfWeek.delete(7);
+        dayOfWeek.add(0);
+    }
+    return {
+        minute: sets[0],
+        hour: sets[1],
+        dayOfMonth: sets[2],
+        month: sets[3],
+        dayOfWeek,
+        dayFieldsAreOr: parts[2] !== "*" && parts[4] !== "*",
+    };
+}
+function parseField(raw, spec, expression) {
+    const out = new Set();
+    for (const term of raw.split(",")) {
+        const [rangePart, stepPart] = term.split("/");
+        const step = stepPart === undefined ? 1 : Number(stepPart);
+        if (!Number.isInteger(step) || step < 1) {
+            throw new ConfigError(`invalid step "${stepPart}" in cron expression "${expression}"`);
+        }
+        let from;
+        let to;
+        if (rangePart === "*" || rangePart === "?") {
+            from = spec.min;
+            to = spec.max;
+        }
+        else if (rangePart.includes("-")) {
+            const [a, b] = rangePart.split("-");
+            from = toNumber(a, spec, expression);
+            to = toNumber(b, spec, expression);
+        }
+        else {
+            from = toNumber(rangePart, spec, expression);
+            // A bare value with a step means "from here to the end", per crontab(5).
+            to = stepPart === undefined ? from : spec.max;
+        }
+        if (from > to) {
+            throw new ConfigError(`range ${from}-${to} is inverted in cron expression "${expression}"`);
+        }
+        for (let value = from; value <= to; value += step)
+            out.add(value);
+    }
+    if (out.size === 0) {
+        throw new ConfigError(`field "${raw}" matches nothing in cron expression "${expression}"`);
+    }
+    return out;
+}
+function toNumber(token, spec, expression) {
+    const named = spec.names?.indexOf(token.toLowerCase());
+    const value = named !== undefined && named >= 0 ? named + (spec.min === 1 ? 1 : 0) : Number(token);
+    if (!Number.isInteger(value) || value < spec.min || value > spec.max) {
+        throw new ConfigError(`"${token}" is out of range ${spec.min}-${spec.max} in cron expression "${expression}"`);
+    }
+    return value;
+}
+/** Whether a wall-clock instant matches, to the minute. */
+export function matches(fields, date) {
+    if (!fields.minute.has(date.getMinutes()))
+        return false;
+    if (!fields.hour.has(date.getHours()))
+        return false;
+    if (!fields.month.has(date.getMonth() + 1))
+        return false;
+    const domMatch = fields.dayOfMonth.has(date.getDate());
+    const dowMatch = fields.dayOfWeek.has(date.getDay());
+    // The OR rule: with both fields restricted, either one firing is enough.
+    return fields.dayFieldsAreOr ? domMatch || dowMatch : domMatch && dowMatch;
+}
+/**
+ * The next instant at or after `from` that matches.
+ *
+ * Steps a minute at a time rather than solving the fields analytically: it is
+ * a few thousand iterations at worst, and it stays correct across DST shifts
+ * because it asks the platform's calendar rather than doing date arithmetic.
+ * Returns undefined if nothing matches within four years (e.g. Feb 30).
+ */
+export function nextRun(fields, from = new Date()) {
+    const cursor = new Date(from.getTime());
+    cursor.setSeconds(0, 0);
+    cursor.setMinutes(cursor.getMinutes() + 1);
+    const limit = 4 * 366 * 24 * 60;
+    for (let i = 0; i < limit; i++) {
+        if (matches(fields, cursor))
+            return cursor;
+        cursor.setMinutes(cursor.getMinutes() + 1);
+    }
+    return undefined;
+}
+/** Describe a schedule in words, for `schedule list`. */
+export function describeCron(expression) {
+    const alias = Object.entries(ALIASES).find(([name]) => name === expression.trim().toLowerCase());
+    if (alias)
+        return `${alias[0].slice(1)} (${alias[1]})`;
+    return expression.trim();
+}
+//# sourceMappingURL=cron.js.map

package/dist/schedule/cron.js.map

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

package/dist/schedule/scheduler.d.ts

@@ -0,0 +1,87 @@
+import type { Harness } from "../harness.ts";
+import type { PermissionMode } from "../agent/permissions.ts";
+export interface ScheduleDefinition {
+    name: string;
+    /** Five-field cron, or an `@daily`-style alias. */
+    cron: string;
+    /** The prompt each firing runs. */
+    prompt: string;
+    model?: string;
+    /**
+     * Defaults to `bypassPermissions`: a scheduled run has nobody to ask, so
+     * anything else silently blocks on the first approval and looks like a hang.
+     * Constrain it with `permissions` rules instead of an interactive mode.
+     */
+    permissionMode?: PermissionMode;
+    maxTurns?: number;
+    enabled?: boolean;
+    /** Working directory for the run; defaults to the harness cwd. */
+    cwd?: string;
+}
+export interface ScheduleRun {
+    schedule: string;
+    startedAt: number;
+    finishedAt: number;
+    sessionId: string;
+    ok: boolean;
+    turns: number;
+    costUsd: number;
+    /** Final assistant text, truncated. */
+    output: string;
+    error?: string;
+}
+export interface ScheduleStatus {
+    name: string;
+    cron: string;
+    enabled: boolean;
+    nextRunAt?: number;
+    lastRun?: ScheduleRun;
+}
+/**
+ * Runs prompts on a cron schedule.
+ *
+ * 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
+ * itself into uselessness within a week, and a failure would poison every
+ * subsequent run.
+ */
+export declare class Scheduler {
+    private readonly harness;
+    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?: {
+        runDir?: string;
+    });
+    add(def: ScheduleDefinition): this;
+    remove(name: string): boolean;
+    list(): ScheduleDefinition[];
+    status(): Promise<ScheduleStatus[]>;
+    /**
+     * Run one schedule now, regardless of its cron.
+     *
+     * This is also how you test a schedule — waiting until midnight to discover
+     * the prompt was wrong is a poor development loop.
+     */
+    runNow(name: string): Promise<ScheduleRun>;
+    /**
+     * Start firing on schedule.
+     *
+     * 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.
+     */
+    start(): void;
+    stop(): void;
+    /** Resolves when every in-flight run has finished. */
+    drain(): Promise<void>;
+    private execute;
+    private recordRun;
+    private lastRun;
+    /** Past runs, newest first. */
+    history(name: string, limit?: number): Promise<ScheduleRun[]>;
+}

package/dist/schedule/scheduler.js

@@ -0,0 +1,237 @@
+import { userPath } from "../paths.js";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { ConfigError, errorMessage } from "../core/errors.js";
+import { messageText } from "../core/types.js";
+import { createLogger } from "../util/logger.js";
+import { parseJson } from "../util/json.js";
+import { nextRun, parseCron } from "./cron.js";
+const MAX_OUTPUT_CHARS = 4_000;
+/**
+ * Runs prompts on a cron schedule.
+ *
+ * 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
+ * itself into uselessness within a week, and a failure would poison every
+ * subsequent run.
+ */
+export class Scheduler {
+    harness;
+    logger;
+    schedules = new Map();
+    runDir;
+    timer;
+    running = false;
+    /** Names currently executing, so a slow job cannot overlap itself. */
+    inFlight = new Set();
+    constructor(harness, definitions = [], opts = {}) {
+        this.harness = harness;
+        this.logger = harness.logger.child("scheduler");
+        this.runDir = opts.runDir ?? userPath("schedules");
+        for (const def of definitions)
+            this.add(def);
+    }
+    add(def) {
+        if (!def.name)
+            throw new ConfigError("a schedule needs a name");
+        if (!def.prompt)
+            throw new ConfigError(`schedule "${def.name}" has no prompt`);
+        // Parse eagerly: a bad expression should fail at load, not at 3am.
+        this.schedules.set(def.name, { def, fields: parseCron(def.cron) });
+        return this;
+    }
+    remove(name) {
+        return this.schedules.delete(name);
+    }
+    list() {
+        return [...this.schedules.values()].map((entry) => entry.def);
+    }
+    async status() {
+        const out = [];
+        for (const { def, fields } of this.schedules.values()) {
+            const enabled = def.enabled !== false;
+            out.push({
+                name: def.name,
+                cron: def.cron,
+                enabled,
+                nextRunAt: enabled ? nextRun(fields)?.getTime() : undefined,
+                lastRun: await this.lastRun(def.name),
+            });
+        }
+        return out;
+    }
+    /**
+     * Run one schedule now, regardless of its cron.
+     *
+     * This is also how you test a schedule — waiting until midnight to discover
+     * the prompt was wrong is a poor development loop.
+     */
+    async runNow(name) {
+        const entry = this.schedules.get(name);
+        if (!entry)
+            throw new ConfigError(`no schedule named "${name}"`);
+        return this.execute(entry.def);
+    }
+    /**
+     * Start firing on schedule.
+     *
+     * 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.
+     */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        let lastMinute = -1;
+        const tick = () => {
+            const now = new Date();
+            const minute = Math.floor(now.getTime() / 60_000);
+            // Only evaluate once per wall-clock minute, however often we wake.
+            if (minute === lastMinute)
+                return;
+            lastMinute = minute;
+            for (const { def, fields } of this.schedules.values()) {
+                if (def.enabled === false)
+                    continue;
+                if (!matchesNow(fields, now))
+                    continue;
+                if (this.inFlight.has(def.name)) {
+                    // A run still going when the next occurrence arrives means the job
+                    // is slower than its interval; skipping is safer than piling up.
+                    this.logger.warn("skipping overlapping run", { schedule: def.name });
+                    continue;
+                }
+                void this.execute(def);
+            }
+        };
+        this.timer = setInterval(tick, 30_000);
+        // Do not hold the process open on our account; the CLI daemon decides.
+        this.timer.unref?.();
+        tick();
+    }
+    stop() {
+        this.running = false;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    /** Resolves when every in-flight run has finished. */
+    async drain() {
+        while (this.inFlight.size > 0) {
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+    }
+    async execute(def) {
+        this.inFlight.add(def.name);
+        const startedAt = Date.now();
+        this.logger.info("running schedule", { schedule: def.name });
+        const session = this.harness.createSession({
+            model: def.model,
+            title: `schedule: ${def.name}`,
+        });
+        const agent = this.harness.agent(session, {
+            // Nobody is at the keyboard to approve anything.
+            permissionPrompt: async () => false,
+            ...(def.maxTurns !== undefined ? { maxTurns: def.maxTurns } : {}),
+        });
+        session.permissions.setMode(def.permissionMode ?? "bypassPermissions");
+        let output = "";
+        let ok = true;
+        let error;
+        try {
+            for await (const event of agent.run(def.prompt)) {
+                if (event.type === "assistant_message")
+                    output = messageText(event.message) || output;
+                if (event.type === "error" && event.fatal) {
+                    ok = false;
+                    error = event.error;
+                }
+            }
+        }
+        catch (err) {
+            ok = false;
+            error = errorMessage(err);
+            this.logger.error("schedule failed", { schedule: def.name, error });
+        }
+        finally {
+            await agent.end().catch(() => { });
+            this.inFlight.delete(def.name);
+        }
+        const run = {
+            schedule: def.name,
+            startedAt,
+            finishedAt: Date.now(),
+            sessionId: session.id,
+            ok,
+            turns: session.turns,
+            costUsd: session.costUsd,
+            output: output.slice(0, MAX_OUTPUT_CHARS),
+            ...(error ? { error } : {}),
+        };
+        await this.recordRun(run).catch((err) => this.logger.warn("could not record the run", { error: String(err) }));
+        return run;
+    }
+    async recordRun(run) {
+        await mkdir(this.runDir, { recursive: true });
+        await appendFile(path.join(this.runDir, `${safeName(run.schedule)}.jsonl`), `${JSON.stringify(run)}\n`, "utf8");
+    }
+    async lastRun(name) {
+        let raw;
+        try {
+            raw = await readFile(path.join(this.runDir, `${safeName(name)}.jsonl`), "utf8");
+        }
+        catch {
+            return undefined;
+        }
+        const lines = raw.split("\n").filter((line) => line.trim() !== "");
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const parsed = parseJson(lines[i]);
+            if (parsed.ok)
+                return parsed.value;
+        }
+        return undefined;
+    }
+    /** Past runs, newest first. */
+    async history(name, limit = 20) {
+        let raw;
+        try {
+            raw = await readFile(path.join(this.runDir, `${safeName(name)}.jsonl`), "utf8");
+        }
+        catch {
+            return [];
+        }
+        const runs = [];
+        for (const line of raw.split("\n")) {
+            if (line.trim() === "")
+                continue;
+            const parsed = parseJson(line);
+            if (parsed.ok)
+                runs.push(parsed.value);
+        }
+        return runs.reverse().slice(0, limit);
+    }
+}
+/** A schedule name becomes a filename, so keep it to safe characters. */
+function safeName(name) {
+    return name.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+function matchesNow(fields, now) {
+    // `matches` is minute-granular and `now` carries seconds; zero them so a
+    // tick at 12:00:37 still counts as 12:00.
+    const minute = new Date(now.getTime());
+    minute.setSeconds(0, 0);
+    return matchesMinute(fields, minute);
+}
+function matchesMinute(fields, date) {
+    if (!fields.minute.has(date.getMinutes()))
+        return false;
+    if (!fields.hour.has(date.getHours()))
+        return false;
+    if (!fields.month.has(date.getMonth() + 1))
+        return false;
+    const dom = fields.dayOfMonth.has(date.getDate());
+    const dow = fields.dayOfWeek.has(date.getDay());
+    return fields.dayFieldsAreOr ? dom || dow : dom && dow;
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/schedule/scheduler.js.map

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

package/dist/storage/kv.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A directory of JSON files, addressed by key.
+ *
+ * A key is a path: `["session", projectId, sessionId]` is one file. That is the
+ * whole abstraction, and it is deliberate — the store has to stay something a
+ * person can open in a file browser and read, because a transcript nobody can
+ * recover by hand is a transcript that can be lost by a bug in this file.
+ *
+ * Two shapes live here. Documents (`.json`) are read and written whole; logs
+ * (`.jsonl`) are appended a line at a time so a crashed process still leaves
+ * everything written before it, and so appending never rewrites what is
+ * already there.
+ */
+export declare class JsonStore {
+    readonly root: string;
+    constructor(root: string);
+    /** Path of a document key. */
+    file(key: string[]): string;
+    /** Path of a log key. */
+    log(key: string[]): string;
+    read<T>(key: string[]): Promise<T | undefined>;
+    /**
+     * Write a document.
+     *
+     * Temp file plus rename: a process killed mid-write would otherwise leave a
+     * truncated file, and a half-written meta.json is a session that has
+     * disappeared as far as every reader is concerned.
+     */
+    write(key: string[], value: unknown): Promise<void>;
+    remove(key: string[]): Promise<void>;
+    removeLog(key: string[]): Promise<void>;
+    /** Every document key under a prefix, depth-first, sorted. */
+    list(prefix: string[]): Promise<string[][]>;
+    /**
+     * Every log key under a prefix, depth-first, sorted.
+     *
+     * The counterpart to `list`, and it exists for the same reason: something
+     * has to be able to answer "which sessions wrote artifacts" without opening
+     * a session to ask it. A readdir answers that; reading the logs to find out
+     * would be reading everything on the machine to decide what to read.
+     */
+    listLogs(prefix: string[]): Promise<string[][]>;
+    private keysUnder;
+    append(key: string[], lines: unknown[]): Promise<void>;
+    /** Rewrite a log wholesale. Only compaction does this; appends are the norm. */
+    replaceLog(key: string[], lines: unknown[]): Promise<void>;
+    /**
+     * Read a log.
+     *
+     * Corrupt lines are skipped rather than failing the read: a torn final line
+     * from a killed process should cost that one line, not the transcript.
+     * `maxBytes` reads the tail instead of the whole file, for logs that grow
+     * without bound.
+     */
+    readLog<T>(key: string[], maxBytes?: number): Promise<T[]>;
+}