cool-workflow 0.1.78

package/dist/scheduler.js

@@ -0,0 +1,266 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Scheduler = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const state_1 = require("./state");
+const DEFAULT_TTL_DAYS = 7;
+class Scheduler {
+    cwd;
+    storePath;
+    constructor(cwd = process.cwd()) {
+        this.cwd = node_path_1.default.resolve(cwd);
+        this.storePath = node_path_1.default.join(this.cwd, ".cw", "schedules", "tasks.json");
+    }
+    create(options) {
+        const kind = normalizeKind(options.kind);
+        const now = new Date();
+        const intervalMinutes = numberOption(options.intervalMinutes || options.interval);
+        const cron = stringOption(options.cron);
+        const delayMinutes = numberOption(options.delayMinutes || options.delay);
+        const jitterSeconds = numberOption(options.jitterSeconds) ?? 0;
+        const nextRunAt = computeInitialNextRunAt({ kind, now, intervalMinutes, cron, delayMinutes, jitterSeconds });
+        const ttlDays = numberOption(options.ttlDays) ?? DEFAULT_TTL_DAYS;
+        const task = {
+            id: createScheduleId(kind),
+            kind,
+            status: "active",
+            createdAt: now.toISOString(),
+            updatedAt: now.toISOString(),
+            nextRunAt: nextRunAt.toISOString(),
+            expiresAt: new Date(now.getTime() + ttlDays * 24 * 60 * 60 * 1000).toISOString(),
+            prompt: requiredString(options.prompt, "prompt"),
+            workflowId: stringOption(options.workflowId),
+            runId: stringOption(options.runId),
+            sessionId: stringOption(options.sessionId),
+            intervalMinutes,
+            cron,
+            jitterSeconds,
+            maxRuns: numberOption(options.maxRuns),
+            runCount: 0
+        };
+        const store = this.load();
+        store.tasks.push(task);
+        this.save(store);
+        return task;
+    }
+    list(status) {
+        const store = this.load();
+        return status ? store.tasks.filter((task) => task.status === status) : store.tasks;
+    }
+    delete(id) {
+        const store = this.load();
+        const before = store.tasks.length;
+        store.tasks = store.tasks.filter((task) => task.id !== id);
+        this.save(store);
+        return { deleted: store.tasks.length !== before, id };
+    }
+    due(now = new Date()) {
+        const store = this.load();
+        let changed = false;
+        for (const task of store.tasks) {
+            if (task.status === "active" && new Date(task.expiresAt).getTime() <= now.getTime()) {
+                task.status = "expired";
+                task.updatedAt = now.toISOString();
+                changed = true;
+            }
+        }
+        if (changed)
+            this.save(store);
+        const dueTasks = store.tasks.filter((task) => task.status === "active" && new Date(task.nextRunAt).getTime() <= now.getTime());
+        if (dueTasks.length) {
+            for (const task of dueTasks) {
+                const alreadyRecorded = task.lastDueAt && new Date(task.lastDueAt).getTime() >= new Date(task.nextRunAt).getTime();
+                if (alreadyRecorded)
+                    continue;
+                task.lastDueAt = now.toISOString();
+                store.history.push(createHistoryRecord(task, "due", this.cwd, now));
+                changed = true;
+            }
+        }
+        if (changed)
+            this.save(store);
+        return dueTasks;
+    }
+    complete(id, options = {}) {
+        const store = this.load();
+        const task = store.tasks.find((candidate) => candidate.id === id);
+        if (!task)
+            throw new Error(`Scheduled task not found: ${id}`);
+        const now = new Date();
+        task.runCount += 1;
+        task.lastRunAt = now.toISOString();
+        task.updatedAt = now.toISOString();
+        const maxRuns = numberOption(options.maxRuns) ?? task.maxRuns;
+        if (maxRuns !== undefined)
+            task.maxRuns = maxRuns;
+        if (task.kind === "reminder" || (task.maxRuns !== undefined && task.runCount >= task.maxRuns)) {
+            task.status = "completed";
+        }
+        else {
+            task.nextRunAt = computeNextRunAt(task, now).toISOString();
+        }
+        this.save(store);
+        return task;
+    }
+    pause(id) {
+        return this.setStatus(id, "paused");
+    }
+    resume(id) {
+        const store = this.load();
+        const task = findTask(store, id);
+        const now = new Date();
+        task.status = "active";
+        task.updatedAt = now.toISOString();
+        if (new Date(task.nextRunAt).getTime() <= now.getTime()) {
+            task.nextRunAt = computeNextRunAt(task, now).toISOString();
+        }
+        this.save(store);
+        return task;
+    }
+    runNow(id) {
+        const store = this.load();
+        const task = findTask(store, id);
+        const now = new Date();
+        task.lastDueAt = now.toISOString();
+        task.updatedAt = now.toISOString();
+        const record = createHistoryRecord(task, "started", this.cwd, now);
+        store.history.push(record);
+        this.save(store);
+        return record;
+    }
+    history(id) {
+        const store = this.load();
+        return id ? store.history.filter((record) => record.scheduleId === id) : store.history;
+    }
+    setStatus(id, status) {
+        const store = this.load();
+        const task = findTask(store, id);
+        task.status = status;
+        task.updatedAt = new Date().toISOString();
+        this.save(store);
+        return task;
+    }
+    load() {
+        if (!node_fs_1.default.existsSync(this.storePath))
+            return { schemaVersion: 1, tasks: [], history: [] };
+        const value = (0, state_1.readJson)(this.storePath);
+        return {
+            schemaVersion: 1,
+            tasks: Array.isArray(value.tasks) ? value.tasks : [],
+            history: Array.isArray(value.history) ? value.history : []
+        };
+    }
+    save(store) {
+        // Authoritative scheduler store — atomic + durable (v0.1.40). writeJson is now
+        // always atomic (temp → rename), so a crash mid-write can never truncate it.
+        (0, state_1.writeJson)(this.storePath, store, { durable: true });
+    }
+}
+exports.Scheduler = Scheduler;
+function findTask(store, id) {
+    const task = store.tasks.find((candidate) => candidate.id === id);
+    if (!task)
+        throw new Error(`Scheduled task not found: ${id}`);
+    return task;
+}
+function createHistoryRecord(task, status, cwd, now) {
+    return {
+        id: createScheduleRunId(task.kind),
+        scheduleId: task.id,
+        status,
+        dueAt: now.toISOString(),
+        startedAt: status === "started" ? now.toISOString() : undefined,
+        prompt: task.prompt,
+        cwd,
+        workflowId: task.workflowId,
+        runId: task.runId
+    };
+}
+function normalizeKind(value) {
+    const kind = String(value || "loop");
+    if (["loop", "cron", "reminder"].includes(kind))
+        return kind;
+    throw new Error(`Unsupported schedule kind: ${kind}`);
+}
+function computeInitialNextRunAt(options) {
+    if (options.kind === "reminder") {
+        return addJitter(new Date(options.now.getTime() + (options.delayMinutes ?? options.intervalMinutes ?? 1) * 60 * 1000), options.jitterSeconds);
+    }
+    if (options.kind === "cron") {
+        if (!options.cron)
+            throw new Error("cron schedule requires --cron");
+        return addJitter(nextFromCron(options.cron, options.now), options.jitterSeconds);
+    }
+    return addJitter(new Date(options.now.getTime() + (options.intervalMinutes ?? 1) * 60 * 1000), options.jitterSeconds);
+}
+function computeNextRunAt(task, now) {
+    if (task.kind === "cron" && task.cron)
+        return addJitter(nextFromCron(task.cron, now), task.jitterSeconds);
+    return addJitter(new Date(now.getTime() + (task.intervalMinutes ?? 1) * 60 * 1000), task.jitterSeconds);
+}
+function nextFromCron(cron, now) {
+    const parts = cron.trim().split(/\s+/);
+    if (parts.length !== 5)
+        throw new Error("Only 5-field cron expressions are supported");
+    const [minuteExpr, hourExpr, dayExpr, monthExpr, weekdayExpr] = parts;
+    const cursor = new Date(now.getTime() + 60 * 1000);
+    cursor.setSeconds(0, 0);
+    for (let attempt = 0; attempt < 8 * 24 * 60; attempt += 1) {
+        if (matchesCron(cursor.getMinutes(), minuteExpr, 0, 59) &&
+            matchesCron(cursor.getHours(), hourExpr, 0, 23) &&
+            matchesCron(cursor.getDate(), dayExpr, 1, 31) &&
+            matchesCron(cursor.getMonth() + 1, monthExpr, 1, 12) &&
+            matchesCron(cursor.getDay(), weekdayExpr, 0, 6)) {
+            return cursor;
+        }
+        cursor.setMinutes(cursor.getMinutes() + 1);
+    }
+    throw new Error("Unable to resolve next cron run within 8 days");
+}
+function matchesCron(value, expr, min, max) {
+    if (expr === "*")
+        return true;
+    if (expr.startsWith("*/")) {
+        const step = Number(expr.slice(2));
+        return Number.isFinite(step) && step > 0 && value % step === 0;
+    }
+    return expr.split(",").some((part) => {
+        const parsed = Number(part);
+        return Number.isInteger(parsed) && parsed >= min && parsed <= max && parsed === value;
+    });
+}
+function addJitter(date, jitterSeconds) {
+    if (!jitterSeconds)
+        return date;
+    const offset = Math.floor(Math.random() * (jitterSeconds + 1)) * 1000;
+    return new Date(date.getTime() + offset);
+}
+function createScheduleId(kind) {
+    const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "Z");
+    return `${kind}-${stamp}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function createScheduleRunId(kind) {
+    const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "Z");
+    return `run-${kind}-${stamp}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function requiredString(value, name) {
+    const text = stringOption(value);
+    if (!text)
+        throw new Error(`Missing required ${name}`);
+    return text;
+}
+function stringOption(value) {
+    if (value === undefined || value === null || value === true)
+        return undefined;
+    return String(value);
+}
+function numberOption(value) {
+    if (value === undefined || value === null || value === true)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}

package/dist/scheduling.js

@@ -0,0 +1,184 @@
+"use strict";
+// Control-Plane Scheduling (v0.1.37) — policy-as-data over the v0.1.28 Run
+// Registry queue. The queue has ORDER; this PURE core adds the scheduling policy:
+// priority+readiness selection, a hard concurrency ceiling, leases, retry with
+// computed backoff, and a fail-closed park state.
+//
+// BSD discipline:
+//  - MECHANISM vs POLICY: these functions are mechanism; the SchedulingPolicy is
+//    data (concurrency, retry budget, backoff curve, lease TTL), kept out of the
+//    kernel and defaulting to conservative fail-closed values.
+//  - FAIL CLOSED [load-bearing]: a concurrency ceiling is NEVER exceeded; an entry
+//    at maxAttempts is PARKED and never re-selected (only `reset` recovers it) —
+//    the queue can never re-hand a failing entry forever.
+//  - DETERMINISTIC: every function takes an injected `now`; selection reuses the
+//    registry's compareQueue; backoff is a pure curve with NO randomness. The
+//    `plan` is read-only and replayable.
+//  - REUSE, don't fork: operates on the existing RunQueueEntry[] from the registry
+//    queue store; does not duplicate the queue file.
+//
+// See docs/control-plane-scheduling.7.md.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SCHEDULING_POLICY = exports.SCHEDULING_SCHEMA_VERSION = void 0;
+exports.normalizeSchedulingPolicy = normalizeSchedulingPolicy;
+exports.backoffMs = backoffMs;
+exports.planSchedule = planSchedule;
+exports.applyLease = applyLease;
+exports.retryOrPark = retryOrPark;
+exports.reclaimExpired = reclaimExpired;
+exports.leaseComplete = leaseComplete;
+exports.leaseRelease = leaseRelease;
+exports.resetEntry = resetEntry;
+const run_registry_1 = require("./run-registry");
+exports.SCHEDULING_SCHEMA_VERSION = 1;
+/** Conservative fail-closed defaults: serial, bounded retries, exponential backoff. */
+exports.DEFAULT_SCHEDULING_POLICY = {
+    schemaVersion: 1,
+    maxConcurrent: 1,
+    maxAttempts: 3,
+    leaseTtlMs: 300_000,
+    backoffBaseMs: 1_000,
+    backoffFactor: 2,
+    backoffCapMs: 60_000
+};
+function normalizeSchedulingPolicy(input) {
+    const base = exports.DEFAULT_SCHEDULING_POLICY;
+    const num = (value, fallback, min) => typeof value === "number" && Number.isFinite(value) && value >= min ? value : fallback;
+    return {
+        schemaVersion: 1,
+        maxConcurrent: num(input?.maxConcurrent, base.maxConcurrent, 1),
+        maxAttempts: num(input?.maxAttempts, base.maxAttempts, 1),
+        leaseTtlMs: num(input?.leaseTtlMs, base.leaseTtlMs, 1),
+        backoffBaseMs: num(input?.backoffBaseMs, base.backoffBaseMs, 0),
+        backoffFactor: num(input?.backoffFactor, base.backoffFactor, 1),
+        backoffCapMs: num(input?.backoffCapMs, base.backoffCapMs, 0)
+    };
+}
+/** Deterministic backoff: baseMs * factor^(attempts-1), capped. No jitter. */
+function backoffMs(policy, attempts) {
+    const raw = policy.backoffBaseMs * Math.pow(policy.backoffFactor, Math.max(0, attempts - 1));
+    return Math.min(Math.round(raw), policy.backoffCapMs);
+}
+function addMs(now, ms) {
+    return new Date(new Date(now).getTime() + ms).toISOString();
+}
+function leaseActive(entry, now) {
+    return entry.status === "leased" && Boolean(entry.leaseExpiresAt) && entry.leaseExpiresAt > now;
+}
+function leaseExpired(entry, now) {
+    return entry.status === "leased" && (!entry.leaseExpiresAt || entry.leaseExpiresAt <= now);
+}
+/** Eligible = pending/ready, not parked/terminal/leased, and past any backoff. */
+function eligible(entry, now) {
+    if (entry.status !== "pending" && entry.status !== "ready")
+        return false;
+    if (entry.nextEligibleAt && entry.nextEligibleAt > now)
+        return false;
+    return true;
+}
+/** Read-only lease plan for the current queue + policy + now. Pure: no mutation. */
+function planSchedule(entries, policy, now) {
+    const sorted = [...entries].sort(run_registry_1.compareQueue);
+    const inFlight = sorted.filter((entry) => leaseActive(entry, now)).length;
+    const available = Math.max(0, policy.maxConcurrent - inFlight);
+    const leases = [];
+    const skipped = [];
+    for (const entry of sorted) {
+        if (leaseActive(entry, now))
+            continue; // counted in inFlight
+        if (entry.status === "parked") {
+            skipped.push({ id: entry.id, reason: "parked" });
+            continue;
+        }
+        if (entry.status === "drained" || entry.status === "cancelled") {
+            skipped.push({ id: entry.id, reason: "terminal" });
+            continue;
+        }
+        if (!eligible(entry, now)) {
+            skipped.push({ id: entry.id, reason: leaseExpired(entry, now) ? "leased" : "backoff" });
+            continue;
+        }
+        if (leases.length >= available) {
+            skipped.push({ id: entry.id, reason: "concurrency-ceiling" });
+            continue;
+        }
+        leases.push({
+            id: entry.id,
+            leaseId: `lease-${entry.id}-${(entry.attempts || 0) + 1}-${now.replace(/[^0-9]/g, "")}`,
+            leaseExpiresAt: addMs(now, policy.leaseTtlMs),
+            attempts: entry.attempts || 0,
+            priority: entry.priority
+        });
+    }
+    return { schemaVersion: 1, now, maxConcurrent: policy.maxConcurrent, inFlight, available, leases, skipped };
+}
+/** Apply the plan: mark the selected entries leased. Never exceeds the ceiling.
+ *  Returns the new entries + the granted leases. */
+function applyLease(entries, policy, now, limit) {
+    const plan = planSchedule(entries, policy, now);
+    const granted = typeof limit === "number" ? plan.leases.slice(0, Math.max(0, limit)) : plan.leases;
+    const byId = new Map(granted.map((lease) => [lease.id, lease]));
+    const next = entries.map((entry) => {
+        const lease = byId.get(entry.id);
+        if (!lease)
+            return entry;
+        return { ...entry, status: "leased", leaseId: lease.leaseId, leaseExpiresAt: lease.leaseExpiresAt };
+    });
+    return { entries: next, leases: granted };
+}
+/** A failed/expired attempt: increment attempts, then park (at budget) or set
+ *  ready with backoff. Fail closed — parked is terminal until reset. */
+function retryOrPark(entry, policy, now, reason) {
+    const attempts = (entry.attempts || 0) + 1;
+    const cleared = { ...entry, attempts, leaseId: undefined, leaseExpiresAt: undefined };
+    if (attempts >= policy.maxAttempts) {
+        return { ...cleared, status: "parked", parkedReason: `${reason} (attempt ${attempts}/${policy.maxAttempts})` };
+    }
+    return { ...cleared, status: "ready", nextEligibleAt: addMs(now, backoffMs(policy, attempts)) };
+}
+/** Reclaim expired leases (host died): each counts as one failed attempt. */
+function reclaimExpired(entries, policy, now) {
+    const reclaimed = [];
+    const next = entries.map((entry) => {
+        if (!leaseExpired(entry, now))
+            return entry;
+        reclaimed.push(entry.id);
+        return retryOrPark(entry, policy, now, "lease expired (host did not complete)");
+    });
+    return { entries: next, reclaimed };
+}
+/** Complete a lease: terminal success. */
+function leaseComplete(entries, leaseId, now) {
+    let matched = false;
+    const next = entries.map((entry) => {
+        if (entry.leaseId !== leaseId || entry.status !== "leased")
+            return entry;
+        matched = true;
+        return { ...entry, status: "drained", drainedAt: now, leaseId: undefined, leaseExpiresAt: undefined };
+    });
+    return { entries: next, matched };
+}
+/** Release a lease: failed -> attempt+backoff/park; otherwise back to ready. */
+function leaseRelease(entries, leaseId, policy, now, options = {}) {
+    let matched = false;
+    const next = entries.map((entry) => {
+        if (entry.leaseId !== leaseId || entry.status !== "leased")
+            return entry;
+        matched = true;
+        if (options.failed)
+            return retryOrPark(entry, policy, now, options.reason || "released as failed");
+        return { ...entry, status: "ready", leaseId: undefined, leaseExpiresAt: undefined };
+    });
+    return { entries: next, matched };
+}
+/** Operator recovery: park -> ready, clearing attempts/backoff. The ONLY way back. */
+function resetEntry(entries, id) {
+    let matched = false;
+    const next = entries.map((entry) => {
+        if (entry.id !== id || entry.status !== "parked")
+            return entry;
+        matched = true;
+        return { ...entry, status: "ready", attempts: 0, nextEligibleAt: undefined, parkedReason: undefined };
+    });
+    return { entries: next, matched };
+}

package/dist/schema-validate.js

@@ -0,0 +1,98 @@
+"use strict";
+// Minimal, dependency-free structural schema validation (Track 3).
+//
+// CW declares an optional output `schema` per task (WorkflowTaskDefinition.schema);
+// this enforces it at result-acceptance time so CW only records structured output
+// it has actually validated — the other half of "auditable" (Track 1 proves the
+// telemetry is real; this proves the result SHAPE is what was declared).
+//
+// DELIBERATELY a subset of JSON Schema, NOT a full implementation: it adds NO
+// runtime dependency (the portability red line — CI runs on node/npm/git only).
+// Supported keywords cover structured-agent-output contracts:
+//   type (object|array|string|number|integer|boolean|null, or an array of them),
+//   enum, const, required, properties, additionalProperties (false), items.
+// Unsupported keywords ($ref, allOf/anyOf/oneOf, pattern, formats, numeric
+// bounds) are IGNORED — never silently "passed" as a constraint that wasn't
+// checked; a schema relying on them simply isn't enforced for those keywords.
+// (If full JSON Schema is needed later, swap this module's impl for ajv behind
+// the same signature.)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAgainstSchema = validateAgainstSchema;
+function typeOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value; // object | string | number | boolean | undefined | function
+}
+function matchesType(value, type) {
+    switch (type) {
+        case "object":
+            return value !== null && typeof value === "object" && !Array.isArray(value);
+        case "array":
+            return Array.isArray(value);
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "null":
+            return value === null;
+        default:
+            return true; // unknown declared type ⇒ not enforced (never a false fail)
+    }
+}
+/** Validate `value` against `schema`. Returns a list of human-readable errors;
+ *  empty ⇒ valid. Pure + deterministic; never throws on a malformed schema (an
+ *  unparseable schema constraint is skipped, not treated as a failure). */
+function validateAgainstSchema(value, schema, path = "$") {
+    const errors = [];
+    if (!schema || typeof schema !== "object")
+        return errors;
+    // type
+    if (schema.type !== undefined) {
+        const types = Array.isArray(schema.type) ? schema.type.map(String) : [String(schema.type)];
+        if (!types.some((t) => matchesType(value, t))) {
+            errors.push(`${path}: expected type ${types.join("|")}, got ${typeOf(value)}`);
+            return errors; // type mismatch ⇒ downstream keyword checks would be noise
+        }
+    }
+    // const / enum
+    if ("const" in schema && JSON.stringify(value) !== JSON.stringify(schema.const)) {
+        errors.push(`${path}: expected const ${JSON.stringify(schema.const)}`);
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.some((option) => JSON.stringify(option) === JSON.stringify(value))) {
+        errors.push(`${path}: ${JSON.stringify(value)} is not one of ${JSON.stringify(schema.enum)}`);
+    }
+    // object: required, properties, additionalProperties:false
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        const obj = value;
+        if (Array.isArray(schema.required)) {
+            for (const key of schema.required) {
+                if (!(String(key) in obj))
+                    errors.push(`${path}: missing required property "${String(key)}"`);
+            }
+        }
+        const properties = (schema.properties && typeof schema.properties === "object" ? schema.properties : {});
+        for (const [key, subSchema] of Object.entries(properties)) {
+            if (key in obj)
+                errors.push(...validateAgainstSchema(obj[key], subSchema, `${path}.${key}`));
+        }
+        if (schema.additionalProperties === false) {
+            for (const key of Object.keys(obj)) {
+                if (!(key in properties))
+                    errors.push(`${path}: additional property "${key}" is not allowed`);
+            }
+        }
+    }
+    // array: items (single schema applied to every element)
+    if (Array.isArray(value) && schema.items && typeof schema.items === "object" && !Array.isArray(schema.items)) {
+        value.forEach((element, index) => {
+            errors.push(...validateAgainstSchema(element, schema.items, `${path}[${index}]`));
+        });
+    }
+    return errors;
+}