pi-harness-runtime 0.10.13 → 0.10.14

package/harness/auto-quota-resume.js

@@ -0,0 +1,104 @@
+/**
+ * Auto Quota Resume — schedules automatic job resume when quota resets.
+ *
+ * Flow:
+ *   quota exhaustion detected
+ *     → read h5_resets_at_epoch from mirror
+ *     → compute resumeAt ISO timestamp
+ *     → call machine.setResumeTime(resumeAt)
+ *     → schedule setTimeout for auto-resume
+ *     → at timeout: machine.transition("running")
+ *
+ * Only the 5h window is auto-resumed (provider-reported, predictable).
+ * Weekly/monthly quota exhaustion requires human monitoring.
+ */
+/** Small buffer (ms) before the exact reset time to resume. */
+const RESUME_BUFFER_MS = 10_000; // 10 seconds — resume just before reset
+/** Minimum time to wait before auto-resuming (avoid immediate re-trigger). */
+const MIN_RESUME_DELAY_MS = 5_000; // 5 seconds
+/** Map of jobId → active auto-resume timer handle. */
+const activeTimers = new Map();
+/**
+ * Schedule an auto-resume for a job that was paused due to quota exhaustion.
+ *
+ * Reads the reset epoch from the mirror store for the given provider,
+ * computes the resume time, sets it on the checkpoint, and schedules
+ * a setTimeout to transition back to "running".
+ *
+ * Returns the scheduled resumeAt ISO string, or null if no epoch data
+ * is available (requires human resume).
+ */
+export function scheduleAutoResume(provider, machine, mirrorStore) {
+    const jobId = machine.getCheckpoint()?.jobId;
+    if (!jobId)
+        return null;
+    // Cancel any existing timer for this job
+    cancelAutoResume(jobId);
+    const mirror = mirrorStore.readAll();
+    const record = mirror?.[provider];
+    if (!record)
+        return null;
+    // Only auto-resume on 5h quota exhaustion (has precise epoch)
+    if (typeof record.h5_resets_at_epoch !== "number")
+        return null;
+    const resetEpoch = record.h5_resets_at_epoch;
+    const now = Date.now();
+    const delayMs = Math.max(resetEpoch - now - RESUME_BUFFER_MS, MIN_RESUME_DELAY_MS);
+    const resumeAt = now + delayMs;
+    const resumeAtIso = new Date(resumeAt).toISOString();
+    // Persist to checkpoint so resumeAt survives worker restart
+    machine.setResumeTime(resumeAtIso);
+    // console.log(
+    // 	`[auto-quota-resume] ${provider} 5h quota exhausted.` +
+    // 		` Auto-resume scheduled at ${resumeAtIso} (in ${Math.round(delayMs / 1000)}s)`,
+    // );
+    const timeout = setTimeout(async () => {
+        activeTimers.delete(jobId);
+        const checkpoint = machine.getCheckpoint();
+        if (!checkpoint || checkpoint.status !== "paused_quota") {
+            // Job was manually resumed or cancelled
+            return;
+        }
+        // Check the mirror — if quota is still exhausted, shift the timer
+        const updated = mirrorStore.readAll()?.[provider];
+        if (updated?.h5_resets_at_epoch) {
+            const stillExhausted = Date.now() < updated.h5_resets_at_epoch;
+            if (stillExhausted) {
+                // console.log(
+                // 	`[auto-quota-resume] ${provider} still exhausted at scheduled time.` +
+                // 			` Re-scheduling...`,
+                // );
+                scheduleAutoResume(provider, machine, mirrorStore);
+                return;
+            }
+        }
+        const result = await machine.transition("running");
+        if (result.success) {
+            // console.log(
+            // 	`[auto-quota-resume] Job ${jobId} auto-resumed after ${provider} 5h quota reset.`,
+            // );
+        }
+        else {
+            console.error(`[auto-quota-resume] Auto-resume failed for ${jobId}: ${result.error}`);
+        }
+    }, delayMs);
+    activeTimers.set(jobId, { timeout, resumeAt });
+    return resumeAtIso;
+}
+/**
+ * Cancel the auto-resume timer for a job.
+ * Call this when the job is manually resumed or cancelled.
+ */
+export function cancelAutoResume(jobId) {
+    const existing = activeTimers.get(jobId);
+    if (existing) {
+        clearTimeout(existing.timeout);
+        activeTimers.delete(jobId);
+    }
+}
+/**
+ * Get the scheduled resume time for a job, or null if not scheduled.
+ */
+export function getScheduledResume(jobId) {
+    return activeTimers.get(jobId)?.resumeAt ?? null;
+}

package/harness/blackboard.js

@@ -0,0 +1,258 @@
+/**
+ * Shared Blackboard — RFC-0011
+ *
+ * Durable file-based coordination so agents communicate without the human
+ * acting as message bus.
+ *
+ * Layout:
+ *   harness/blackboard/
+ *     status.json
+ *     next_action.json
+ *     tasks.json
+ *     agent_registry.json
+ *     locks/
+ *     reports/
+ *     context/
+ *     events.jsonl
+ */
+import { writeJson, readJson, appendJsonl, ensureUsageDir } from "../cli.ts";
+// @ts-expect-error - Bun has built-in Node.js types
+import { join } from "node:path";
+export class SharedBlackboard {
+    jobDir;
+    record = null;
+    constructor(jobId, rootDir) {
+        this.jobDir = join(rootDir, "jobs", jobId, "blackboard");
+    }
+    /**
+     * Initialize a new blackboard for a job
+     */
+    init(jobId, taskGraph) {
+        const now = new Date().toISOString();
+        this.record = {
+            jobId,
+            status: "created",
+            nextAction: undefined,
+            tasks: taskGraph,
+            agentRegistry: { agents: {} },
+            reports: {},
+            locks: {},
+            updatedAt: now,
+        };
+        this.save();
+    }
+    /**
+     * Load blackboard from disk
+     */
+    load() {
+        const path = join(this.jobDir, "status.json");
+        this.record = readJson(path);
+        return this.record;
+    }
+    /**
+     * Save blackboard to disk
+     */
+    save() {
+        if (!this.record)
+            return;
+        this.record.updatedAt = new Date().toISOString();
+        ensureUsageDir();
+        const path = join(this.jobDir, "status.json");
+        writeJson(path, this.record);
+    }
+    /**
+     * Update job status
+     */
+    updateStatus(status) {
+        if (!this.record)
+            return;
+        this.record.status = status;
+        this.save();
+        this.appendEvent("StatusUpdated", { status });
+    }
+    /**
+     * Set the next action for agents to pick up
+     */
+    setNextAction(action) {
+        if (!this.record)
+            return;
+        this.record.nextAction = action;
+        this.save();
+        this.appendEvent("NextActionUpdated", {
+            taskId: action.taskId,
+            agentId: action.agentId,
+            priority: action.priority,
+        });
+    }
+    /**
+     * Clear the next action (after agent picks it up)
+     */
+    clearNextAction() {
+        if (!this.record)
+            return;
+        this.record.nextAction = undefined;
+        this.save();
+    }
+    /**
+     * Register an agent
+     */
+    registerAgent(agentId, name, provider, model) {
+        if (!this.record)
+            return;
+        this.record.agentRegistry.agents[agentId] = {
+            id: agentId,
+            name,
+            provider,
+            model,
+            status: "idle",
+            startedAt: new Date().toISOString(),
+        };
+        this.save();
+    }
+    /**
+     * Update agent status
+     */
+    updateAgentStatus(agentId, status, currentTaskId) {
+        if (!this.record)
+            return;
+        const agent = this.record.agentRegistry.agents[agentId];
+        if (!agent)
+            return;
+        agent.status = status;
+        agent.currentTaskId = currentTaskId;
+        agent.lastHeartbeat = new Date().toISOString();
+        this.save();
+    }
+    /**
+     * Unregister an agent
+     */
+    unregisterAgent(agentId) {
+        if (!this.record)
+            return;
+        delete this.record.agentRegistry.agents[agentId];
+        this.save();
+    }
+    /**
+     * Write an agent report
+     */
+    writeReport(report) {
+        if (!this.record)
+            return;
+        this.record.reports[report.agentId] = report;
+        this.save();
+        this.appendEvent("AgentReportWritten", {
+            agentId: report.agentId,
+            taskId: report.taskId,
+            status: report.status,
+        });
+    }
+    /**
+     * Acquire a lock on a task
+     */
+    acquireLock(taskId, agentId) {
+        if (!this.record)
+            return false;
+        if (this.record.locks[taskId]) {
+            return false; // Already locked
+        }
+        this.record.locks[taskId] = {
+            taskId,
+            agentId,
+            acquiredAt: new Date().toISOString(),
+        };
+        this.save();
+        this.appendEvent("LockAcquired", { taskId, agentId });
+        return true;
+    }
+    /**
+     * Release a lock on a task
+     */
+    releaseLock(taskId, agentId) {
+        if (!this.record)
+            return false;
+        const lock = this.record.locks[taskId];
+        if (!lock || lock.agentId !== agentId) {
+            return false; // Not locked by this agent
+        }
+        delete this.record.locks[taskId];
+        this.save();
+        this.appendEvent("LockReleased", { taskId, agentId });
+        return true;
+    }
+    /**
+     * Check if a task is locked
+     */
+    isLocked(taskId) {
+        return !!this.record?.locks[taskId];
+    }
+    /**
+     * Get lock info for a task
+     */
+    getLock(taskId) {
+        return this.record?.locks[taskId] ?? null;
+    }
+    /**
+     * Get the current record
+     */
+    getRecord() {
+        return this.record;
+    }
+    /**
+     * Get active agents
+     */
+    getActiveAgents() {
+        if (!this.record)
+            return [];
+        return Object.values(this.record.agentRegistry.agents);
+    }
+    /**
+     * Check for stale agents (no heartbeat in N minutes)
+     */
+    getStaleAgents(maxAgeMinutes = 10) {
+        if (!this.record)
+            return [];
+        const cutoff = Date.now() - maxAgeMinutes * 60 * 1000;
+        return Object.values(this.record.agentRegistry.agents).filter((a) => {
+            if (!a.lastHeartbeat)
+                return false;
+            return Date.parse(a.lastHeartbeat) < cutoff;
+        });
+    }
+    /**
+     * Append an event to the event log
+     */
+    appendEvent(type, data) {
+        if (!this.record)
+            return;
+        const event = {
+            ts: new Date().toISOString(),
+            jobId: this.record.jobId,
+            type,
+            message: `Blackboard event: ${type}`,
+            data,
+        };
+        const path = join(this.jobDir, "events.jsonl");
+        ensureUsageDir();
+        appendJsonl(path, event);
+    }
+    /**
+     * Export full blackboard state
+     */
+    export() {
+        return JSON.stringify(this.record, null, 2);
+    }
+    /**
+     * Get blackboard directory path
+     */
+    getPath() {
+        return this.jobDir;
+    }
+}
+/**
+ * Create and initialize a blackboard for a job
+ */
+export function createBlackboard(jobId, rootDir, taskGraph) {
+    const blackboard = new SharedBlackboard(jobId, rootDir);
+    blackboard.init(jobId, taskGraph);
+    return blackboard;
+}