@diousk/pi-subagents-fast 0.20.0

package/dist/schedule-store.d.ts

@@ -0,0 +1,38 @@
+/**
+ * schedule-store.ts — File-backed store for scheduled subagents.
+ *
+ * Session-scoped: each pi session owns its own schedules at
+ * `<cwd>/.pi/subagent-schedules/<sessionId>.json`. `/new` starts a fresh
+ * empty store; `/resume` reloads.
+ *
+ * Concurrency model lifted from pi-chonky-tasks/src/task-store.ts: every
+ * mutation acquires a PID-based exclusion lock, re-reads the latest state
+ * from disk, applies the change, atomic-writes via temp+rename, releases.
+ */
+import type { ScheduledSubagent } from "./types.js";
+/** Resolve the storage path for a session-scoped store. */
+export declare function resolveStorePath(cwd: string, sessionId: string): string;
+export declare class ScheduleStore {
+    private filePath;
+    private lockPath;
+    private jobs;
+    constructor(filePath: string);
+    /** Create the backing directory lazily — only when we're about to persist. */
+    private ensureDir;
+    /** Load from disk into the in-memory cache. Silent on parse errors. */
+    private load;
+    /** Atomic write via temp file + rename (POSIX-atomic). */
+    private save;
+    /** Acquire lock → reload → mutate → save → release. */
+    private withLock;
+    /** Read-only — returns a snapshot of the in-memory cache. */
+    list(): ScheduledSubagent[];
+    /** Read-only check — uses the cache. */
+    hasName(name: string, exceptId?: string): boolean;
+    get(id: string): ScheduledSubagent | undefined;
+    add(job: ScheduledSubagent): void;
+    update(id: string, patch: Partial<ScheduledSubagent>): ScheduledSubagent | undefined;
+    remove(id: string): boolean;
+    /** Delete the backing file (used when no jobs remain, optional cleanup). */
+    deleteFileIfEmpty(): void;
+}

package/dist/schedule-store.js

@@ -0,0 +1,155 @@
+/**
+ * schedule-store.ts — File-backed store for scheduled subagents.
+ *
+ * Session-scoped: each pi session owns its own schedules at
+ * `<cwd>/.pi/subagent-schedules/<sessionId>.json`. `/new` starts a fresh
+ * empty store; `/resume` reloads.
+ *
+ * Concurrency model lifted from pi-chonky-tasks/src/task-store.ts: every
+ * mutation acquires a PID-based exclusion lock, re-reads the latest state
+ * from disk, applies the change, atomic-writes via temp+rename, releases.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+const LOCK_RETRY_MS = 50;
+const LOCK_MAX_RETRIES = 100;
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function acquireLock(lockPath) {
+    for (let i = 0; i < LOCK_MAX_RETRIES; i++) {
+        try {
+            writeFileSync(lockPath, `${process.pid}`, { flag: "wx" });
+            return;
+        }
+        catch (e) {
+            if (e.code === "EEXIST") {
+                try {
+                    const pid = parseInt(readFileSync(lockPath, "utf-8"), 10);
+                    if (pid && !isProcessRunning(pid)) {
+                        unlinkSync(lockPath);
+                        continue;
+                    }
+                }
+                catch { /* ignore — try again */ }
+                const start = Date.now();
+                while (Date.now() - start < LOCK_RETRY_MS) { /* busy wait */ }
+                continue;
+            }
+            throw e;
+        }
+    }
+    throw new Error(`Failed to acquire schedule lock: ${lockPath}`);
+}
+function releaseLock(lockPath) {
+    try {
+        unlinkSync(lockPath);
+    }
+    catch { /* ignore */ }
+}
+/** Resolve the storage path for a session-scoped store. */
+export function resolveStorePath(cwd, sessionId) {
+    return join(cwd, ".pi", "subagent-schedules", `${sessionId}.json`);
+}
+export class ScheduleStore {
+    filePath;
+    lockPath;
+    jobs = new Map();
+    constructor(filePath) {
+        this.filePath = filePath;
+        this.lockPath = filePath + ".lock";
+        this.load();
+    }
+    /** Create the backing directory lazily — only when we're about to persist. */
+    ensureDir() {
+        mkdirSync(dirname(this.filePath), { recursive: true });
+    }
+    /** Load from disk into the in-memory cache. Silent on parse errors. */
+    load() {
+        if (!existsSync(this.filePath))
+            return;
+        try {
+            const data = JSON.parse(readFileSync(this.filePath, "utf-8"));
+            this.jobs.clear();
+            for (const j of data.jobs ?? [])
+                this.jobs.set(j.id, j);
+        }
+        catch { /* corrupt — start fresh, next save rewrites */ }
+    }
+    /** Atomic write via temp file + rename (POSIX-atomic). */
+    save() {
+        const data = { version: 1, jobs: [...this.jobs.values()] };
+        const tmp = this.filePath + ".tmp";
+        writeFileSync(tmp, JSON.stringify(data, null, 2));
+        renameSync(tmp, this.filePath);
+    }
+    /** Acquire lock → reload → mutate → save → release. */
+    withLock(fn) {
+        this.ensureDir();
+        acquireLock(this.lockPath);
+        try {
+            this.load();
+            const result = fn();
+            this.save();
+            return result;
+        }
+        finally {
+            releaseLock(this.lockPath);
+        }
+    }
+    /** Read-only — returns a snapshot of the in-memory cache. */
+    list() {
+        return [...this.jobs.values()];
+    }
+    /** Read-only check — uses the cache. */
+    hasName(name, exceptId) {
+        for (const j of this.jobs.values()) {
+            if (j.id !== exceptId && j.name === name)
+                return true;
+        }
+        return false;
+    }
+    get(id) {
+        return this.jobs.get(id);
+    }
+    add(job) {
+        this.withLock(() => {
+            this.jobs.set(job.id, job);
+        });
+    }
+    update(id, patch) {
+        // No-op fast path — an unknown id changes nothing, so don't lock or touch
+        // disk (which would otherwise lazily create the backing directory).
+        if (!this.jobs.has(id))
+            return undefined;
+        return this.withLock(() => {
+            const existing = this.jobs.get(id);
+            if (!existing)
+                return undefined;
+            const updated = { ...existing, ...patch };
+            this.jobs.set(id, updated);
+            return updated;
+        });
+    }
+    remove(id) {
+        // No-op fast path — see update().
+        if (!this.jobs.has(id))
+            return false;
+        return this.withLock(() => this.jobs.delete(id));
+    }
+    /** Delete the backing file (used when no jobs remain, optional cleanup). */
+    deleteFileIfEmpty() {
+        if (this.jobs.size === 0 && existsSync(this.filePath)) {
+            try {
+                unlinkSync(this.filePath);
+            }
+            catch { /* ignore */ }
+        }
+    }
+}

package/dist/schedule.d.ts

@@ -0,0 +1,109 @@
+/**
+ * schedule.ts — `SubagentScheduler`: timer-driven dispatcher of scheduled subagents.
+ *
+ * Mirrors the engine shape of pi-cron-schedule/src/scheduler.ts:
+ *   - two-Map split (jobs = croner Cron, intervals = setInterval/setTimeout)
+ *   - addJob/removeJob/updateJob/scheduleJob/unscheduleJob/executeJob
+ *   - static parsers for cron / "+10m" / "5m" / ISO formats
+ *
+ * Differences vs pi-cron-schedule:
+ *   - Persistence is via ScheduleStore (PID-locked, session-scoped, atomic).
+ *   - `executeJob` calls `manager.spawn(..., { bypassQueue: true })` instead
+ *     of dispatching a user message — schedule fires bypass maxConcurrent so
+ *     a 5-minute interval can't be deferred behind 4 long-running agents.
+ *   - Result delivery is implicit: spawn → background completion → existing
+ *     `subagent-notification` followUp path. No new delivery code.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentManager } from "./agent-manager.js";
+import type { ScheduleStore } from "./schedule-store.js";
+import type { IsolationMode, ScheduledSubagent, SubagentType, ThinkingLevel } from "./types.js";
+/** Event emitted on `pi.events` for cross-extension consumers. */
+export type ScheduleChangeEvent = {
+    type: "added";
+    job: ScheduledSubagent;
+} | {
+    type: "removed";
+    jobId: string;
+} | {
+    type: "updated";
+    job: ScheduledSubagent;
+} | {
+    type: "fired";
+    jobId: string;
+    agentId: string;
+    name: string;
+} | {
+    type: "error";
+    jobId: string;
+    error: string;
+};
+/** Params accepted at job creation — ID, timestamps, and state are derived. */
+export interface NewJobInput {
+    name: string;
+    description: string;
+    schedule: string;
+    subagent_type: SubagentType;
+    prompt: string;
+    model?: string;
+    thinking?: ThinkingLevel;
+    max_turns?: number;
+    isolated?: boolean;
+    isolation?: IsolationMode;
+}
+export declare class SubagentScheduler {
+    private jobs;
+    private intervals;
+    private store;
+    private pi;
+    private ctx;
+    private manager;
+    /** Start the scheduler: bind to a session's store and arm enabled jobs. */
+    start(pi: ExtensionAPI, ctx: ExtensionContext, manager: AgentManager, store: ScheduleStore): void;
+    /** Stop all timers; drop refs. Safe to call repeatedly. */
+    stop(): void;
+    /** True if start() has bound a store and the scheduler is active. */
+    isActive(): boolean;
+    list(): ScheduledSubagent[];
+    /**
+     * Build a `ScheduledSubagent` from user input. Validates the schedule
+     * format and tags `scheduleType`. Throws on invalid input.
+     */
+    buildJob(input: NewJobInput): ScheduledSubagent;
+    /** Add a job, persist, and arm if enabled. Returns the stored job. */
+    addJob(input: NewJobInput): ScheduledSubagent;
+    removeJob(id: string): boolean;
+    /** Toggle / mutate a job. Re-arms based on the new `enabled` state. */
+    updateJob(id: string, patch: Partial<ScheduledSubagent>): ScheduledSubagent | undefined;
+    /** Next-run time as ISO, or undefined if not currently armed. */
+    getNextRun(jobId: string): string | undefined;
+    private scheduleJob;
+    private unscheduleJob;
+    /**
+     * Fire a job: persist running state, spawn (bypassing the concurrency
+     * queue), persist completion. Fire-and-forget: the timer tick returns
+     * immediately so other jobs keep firing.
+     */
+    private executeJob;
+    private emit;
+    private requireStore;
+    /**
+     * Sniff a schedule string and tag its type. Throws on invalid input.
+     * Order matters: relative ("+10m") and interval ("5m") both match digit+unit;
+     * relative requires the leading "+" to disambiguate.
+     */
+    static detectSchedule(s: string): {
+        type: "cron" | "once" | "interval";
+        intervalMs?: number;
+        normalized: string;
+    };
+    /** 6-field cron — 'second minute hour dom month dow'. */
+    static validateCronExpression(expr: string): {
+        valid: boolean;
+        error?: string;
+    };
+    /** "+10s"/"+5m"/"+1h"/"+2d" → ISO timestamp. */
+    static parseRelativeTime(s: string): string | null;
+    /** "10s"/"5m"/"1h"/"2d" → milliseconds. */
+    static parseInterval(s: string): number | null;
+}

package/dist/schedule.js

@@ -0,0 +1,359 @@
+/**
+ * schedule.ts — `SubagentScheduler`: timer-driven dispatcher of scheduled subagents.
+ *
+ * Mirrors the engine shape of pi-cron-schedule/src/scheduler.ts:
+ *   - two-Map split (jobs = croner Cron, intervals = setInterval/setTimeout)
+ *   - addJob/removeJob/updateJob/scheduleJob/unscheduleJob/executeJob
+ *   - static parsers for cron / "+10m" / "5m" / ISO formats
+ *
+ * Differences vs pi-cron-schedule:
+ *   - Persistence is via ScheduleStore (PID-locked, session-scoped, atomic).
+ *   - `executeJob` calls `manager.spawn(..., { bypassQueue: true })` instead
+ *     of dispatching a user message — schedule fires bypass maxConcurrent so
+ *     a 5-minute interval can't be deferred behind 4 long-running agents.
+ *   - Result delivery is implicit: spawn → background completion → existing
+ *     `subagent-notification` followUp path. No new delivery code.
+ */
+import { Cron } from "croner";
+import { nanoid } from "nanoid";
+import { normalizeMaxTurns } from "./agent-runner.js";
+import { resolveSpawnType } from "./agent-types.js";
+import { resolveModel } from "./model-resolver.js";
+export class SubagentScheduler {
+    jobs = new Map();
+    intervals = new Map();
+    store;
+    pi;
+    ctx;
+    manager;
+    /** Start the scheduler: bind to a session's store and arm enabled jobs. */
+    start(pi, ctx, manager, store) {
+        this.pi = pi;
+        this.ctx = ctx;
+        this.manager = manager;
+        this.store = store;
+        for (const job of store.list()) {
+            if (job.enabled)
+                this.scheduleJob(job);
+        }
+    }
+    /** Stop all timers; drop refs. Safe to call repeatedly. */
+    stop() {
+        for (const cron of this.jobs.values())
+            cron.stop();
+        this.jobs.clear();
+        for (const t of this.intervals.values())
+            clearTimeout(t);
+        this.intervals.clear();
+        this.store = undefined;
+        this.pi = undefined;
+        this.ctx = undefined;
+        this.manager = undefined;
+    }
+    /** True if start() has bound a store and the scheduler is active. */
+    isActive() {
+        return this.store !== undefined;
+    }
+    list() {
+        return this.store?.list() ?? [];
+    }
+    /**
+     * Build a `ScheduledSubagent` from user input. Validates the schedule
+     * format and tags `scheduleType`. Throws on invalid input.
+     */
+    buildJob(input) {
+        const detected = SubagentScheduler.detectSchedule(input.schedule);
+        return {
+            id: nanoid(10),
+            name: input.name,
+            description: input.description,
+            schedule: detected.normalized,
+            scheduleType: detected.type,
+            intervalMs: detected.intervalMs,
+            subagent_type: input.subagent_type,
+            prompt: input.prompt,
+            model: input.model,
+            thinking: input.thinking,
+            max_turns: input.max_turns,
+            isolated: input.isolated,
+            isolation: input.isolation,
+            enabled: true,
+            createdAt: new Date().toISOString(),
+            runCount: 0,
+        };
+    }
+    /** Add a job, persist, and arm if enabled. Returns the stored job. */
+    addJob(input) {
+        const store = this.requireStore();
+        if (store.hasName(input.name)) {
+            throw new Error(`A scheduled job named "${input.name}" already exists.`);
+        }
+        const job = this.buildJob(input);
+        store.add(job);
+        if (job.enabled)
+            this.scheduleJob(job);
+        this.emit({ type: "added", job });
+        return job;
+    }
+    removeJob(id) {
+        const store = this.requireStore();
+        if (!store.get(id))
+            return false;
+        this.unscheduleJob(id);
+        const ok = store.remove(id);
+        if (ok)
+            this.emit({ type: "removed", jobId: id });
+        return ok;
+    }
+    /** Toggle / mutate a job. Re-arms based on the new `enabled` state. */
+    updateJob(id, patch) {
+        const store = this.requireStore();
+        const updated = store.update(id, patch);
+        if (!updated)
+            return undefined;
+        this.unscheduleJob(id);
+        if (updated.enabled)
+            this.scheduleJob(updated);
+        this.emit({ type: "updated", job: updated });
+        return updated;
+    }
+    /** Next-run time as ISO, or undefined if not currently armed. */
+    getNextRun(jobId) {
+        const cron = this.jobs.get(jobId);
+        if (cron)
+            return cron.nextRun()?.toISOString();
+        const job = this.store?.get(jobId);
+        if (!job?.enabled)
+            return undefined;
+        if (job.scheduleType === "once")
+            return job.schedule;
+        if (job.scheduleType === "interval" && job.intervalMs) {
+            // Before the first fire there's no `lastRun`, so fall back to "now" —
+            // accurate at create time (setInterval was just armed) and within
+            // intervalMs of correct in any pre-first-fire view.
+            const base = job.lastRun ? new Date(job.lastRun).getTime() : Date.now();
+            return new Date(base + job.intervalMs).toISOString();
+        }
+        return undefined;
+    }
+    // ── Scheduling primitives ────────────────────────────────────────────
+    scheduleJob(job) {
+        const store = this.store;
+        if (!store)
+            return;
+        try {
+            if (job.scheduleType === "interval" && job.intervalMs) {
+                const t = setInterval(() => this.executeJob(job.id), job.intervalMs);
+                this.intervals.set(job.id, t);
+            }
+            else if (job.scheduleType === "once") {
+                const target = new Date(job.schedule).getTime();
+                const delay = target - Date.now();
+                if (delay > 0) {
+                    const t = setTimeout(() => {
+                        this.executeJob(job.id);
+                        // Auto-disable one-shots after they fire (mirrors pi-cron-schedule)
+                        store.update(job.id, { enabled: false });
+                        const updated = store.get(job.id);
+                        if (updated)
+                            this.emit({ type: "updated", job: updated });
+                    }, delay);
+                    this.intervals.set(job.id, t);
+                }
+                else {
+                    // Past timestamp — disable, mark error, never fire
+                    store.update(job.id, { enabled: false, lastStatus: "error" });
+                    this.emit({ type: "error", jobId: job.id, error: `Scheduled time ${job.schedule} is in the past` });
+                }
+            }
+            else {
+                const cron = new Cron(job.schedule, () => this.executeJob(job.id));
+                this.jobs.set(job.id, cron);
+            }
+        }
+        catch (err) {
+            this.emit({ type: "error", jobId: job.id, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    unscheduleJob(id) {
+        const cron = this.jobs.get(id);
+        if (cron) {
+            cron.stop();
+            this.jobs.delete(id);
+        }
+        const t = this.intervals.get(id);
+        if (t) {
+            clearTimeout(t);
+            clearInterval(t);
+            this.intervals.delete(id);
+        }
+    }
+    /**
+     * Fire a job: persist running state, spawn (bypassing the concurrency
+     * queue), persist completion. Fire-and-forget: the timer tick returns
+     * immediately so other jobs keep firing.
+     */
+    executeJob(id) {
+        const store = this.store;
+        const pi = this.pi;
+        const ctx = this.ctx;
+        const manager = this.manager;
+        if (!store || !pi || !ctx || !manager)
+            return;
+        const job = store.get(id);
+        if (!job?.enabled)
+            return;
+        store.update(id, { lastStatus: "running" });
+        // Resolve model at fire time — registry contents may have changed since the
+        // job was created (auth added/removed). Fall back silently to spawn-default
+        // if resolution fails; the spawn path handles undefined model gracefully.
+        let resolvedModel;
+        if (job.model) {
+            const r = resolveModel(job.model, ctx.modelRegistry);
+            if (typeof r !== "string")
+                resolvedModel = r;
+        }
+        let agentId;
+        try {
+            // Re-resolve at fire time against the registry as it stands. This does not
+            // reload from disk (the scheduler has no reason to rebuild process-global
+            // state from a timer), so it catches changes that went through /agents or
+            // an Agent call — not a file deleted directly from a shell. The catch below turns
+            // this into lastStatus: "error" plus an error event, like any other
+            // fire-time failure.
+            const dispatch = resolveSpawnType(job.subagent_type);
+            if (!dispatch.ok)
+                throw new Error(dispatch.message);
+            agentId = manager.spawn(pi, ctx, dispatch.type, job.prompt, {
+                description: job.description,
+                isBackground: true,
+                bypassQueue: true,
+                model: resolvedModel,
+                maxTurns: job.max_turns,
+                isolated: job.isolated,
+                thinkingLevel: job.thinking,
+                isolation: job.isolation,
+                // A scheduled run has no tool call to build this, so without it the
+                // conversation viewer shows nothing about how the job was configured.
+                // The model is left out on purpose: agent-manager fills in the effective
+                // one when the session reports it, and naming the pre-session pick here
+                // would only be right until then.
+                invocation: {
+                    thinking: job.thinking,
+                    // Normalized like the Agent tool's own snapshot: `0` means unlimited,
+                    // and rendering it as "max turns: 0" would read as a limit of none.
+                    maxTurns: normalizeMaxTurns(job.max_turns),
+                    isolated: job.isolated,
+                    runInBackground: true,
+                    isolation: job.isolation,
+                },
+            });
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            store.update(id, { lastRun: new Date().toISOString(), lastStatus: "error" });
+            this.emit({ type: "error", jobId: id, error });
+            return;
+        }
+        this.emit({ type: "fired", jobId: id, agentId, name: job.name });
+        const finalize = (status) => {
+            const next = this.getNextRun(id);
+            const current = store.get(id);
+            store.update(id, {
+                lastRun: new Date().toISOString(),
+                lastStatus: status,
+                runCount: (current?.runCount ?? 0) + 1,
+                nextRun: next,
+            });
+        };
+        // AgentManager's promise resolves either way (its .catch returns ""), so we
+        // can't infer success/failure from the promise — read record.status instead.
+        // Terminal states: completed/steered = success; error/aborted/stopped = error.
+        // awaitStartup first: with isolation: "worktree" the run promise only exists
+        // once the repo copy is made, and a failed copy rejects here.
+        manager.awaitStartup(agentId)
+            .then(() => manager.getRecord(agentId)?.promise)
+            .then(() => {
+            const r = manager.getRecord(agentId);
+            const failed = r?.status === "error" || r?.status === "aborted" || r?.status === "stopped";
+            finalize(failed ? "error" : "success");
+        })
+            .catch(() => finalize("error"));
+    }
+    emit(event) {
+        if (this.pi)
+            this.pi.events.emit("subagents:scheduled", event);
+    }
+    requireStore() {
+        if (!this.store)
+            throw new Error("Scheduler not started — no active session.");
+        return this.store;
+    }
+    // ── Format detection / parsers (statics — pure) ──────────────────────
+    /**
+     * Sniff a schedule string and tag its type. Throws on invalid input.
+     * Order matters: relative ("+10m") and interval ("5m") both match digit+unit;
+     * relative requires the leading "+" to disambiguate.
+     */
+    static detectSchedule(s) {
+        const trimmed = s.trim();
+        // "+10m" — relative one-shot
+        const rel = SubagentScheduler.parseRelativeTime(trimmed);
+        if (rel !== null)
+            return { type: "once", normalized: rel };
+        // "5m" — interval
+        const ivl = SubagentScheduler.parseInterval(trimmed);
+        if (ivl !== null)
+            return { type: "interval", intervalMs: ivl, normalized: trimmed };
+        // ISO timestamp — one-shot. Reject past timestamps upfront so we never
+        // create a dead-on-arrival record (scheduleJob's safety net still catches
+        // micro-races from `+0s`-style relatives).
+        if (/^\d{4}-\d{2}-\d{2}T/.test(trimmed)) {
+            const d = new Date(trimmed);
+            if (!Number.isNaN(d.getTime())) {
+                if (d.getTime() <= Date.now()) {
+                    throw new Error(`Scheduled time ${d.toISOString()} is in the past.`);
+                }
+                return { type: "once", normalized: d.toISOString() };
+            }
+        }
+        // Cron — 6-field
+        const cronCheck = SubagentScheduler.validateCronExpression(trimmed);
+        if (cronCheck.valid)
+            return { type: "cron", normalized: trimmed };
+        throw new Error(`Invalid schedule "${s}". Use 6-field cron (e.g. "0 0 9 * * 1" — 9am every Monday), interval ("5m"/"1h"), or one-shot ("+10m" / ISO).`);
+    }
+    /** 6-field cron — 'second minute hour dom month dow'. */
+    static validateCronExpression(expr) {
+        const fields = expr.trim().split(/\s+/);
+        if (fields.length !== 6) {
+            return {
+                valid: false,
+                error: `Cron must have 6 fields (second minute hour dom month dow), got ${fields.length}. Example: "0 0 9 * * 1" for 9am every Monday.`,
+            };
+        }
+        try {
+            // Croner validates by construction.
+            new Cron(expr, () => { });
+            return { valid: true };
+        }
+        catch (e) {
+            return { valid: false, error: e instanceof Error ? e.message : "Invalid cron expression" };
+        }
+    }
+    /** "+10s"/"+5m"/"+1h"/"+2d" → ISO timestamp. */
+    static parseRelativeTime(s) {
+        const m = s.match(/^\+(\d+)(s|m|h|d)$/);
+        if (!m)
+            return null;
+        const ms = parseInt(m[1], 10) * { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+        return new Date(Date.now() + ms).toISOString();
+    }
+    /** "10s"/"5m"/"1h"/"2d" → milliseconds. */
+    static parseInterval(s) {
+        const m = s.match(/^(\d+)(s|m|h|d)$/);
+        if (!m)
+            return null;
+        return parseInt(m[1], 10) * { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+    }
+}