@runcore-sh/runcore 0.1.8 → 0.1.10

package/dist/agents/heartbeat.js

@@ -0,0 +1,323 @@
+/**
+ * Agent Heartbeat Monitor — CORE-9
+ *
+ * Action-based heartbeat: every agent action IS the ping.
+ * No polling, no timer-based pings. The append-only log is the tracking.
+ *
+ * Monitors:
+ * 1. **Silence detection** — agent produces no output for too long → terminate
+ * 2. **Drift detection** — agent's actions diverge from the assigned task → warn/terminate
+ * 3. **Heartbeat logging** — append-only JSONL trail of agent pulses
+ *
+ * Designed to work with the existing activity log system. Each agent gets
+ * a HeartbeatTracker that watches for signs of life and task adherence.
+ */
+import { join, resolve } from "node:path";
+import { createLogger } from "../utils/logger.js";
+import { logActivity, generateTraceId } from "../activity/log.js";
+import { appendBrainLineSync, ensureBrainFileSync, } from "../lib/brain-io.js";
+const log = createLogger("heartbeat");
+const OPS_DIR = resolve(process.cwd(), "brain", "ops");
+const HEARTBEAT_FILE = join(OPS_DIR, "heartbeats.jsonl");
+const SCHEMA_LINE = JSON.stringify({ _schema: "heartbeat", _version: "1.0" });
+// Ensure the file exists on module load
+try {
+    ensureBrainFileSync(HEARTBEAT_FILE, SCHEMA_LINE);
+}
+catch {
+    // Non-fatal — will retry on first write
+}
+// ---------------------------------------------------------------------------
+// Default config
+// ---------------------------------------------------------------------------
+const DEFAULT_CONFIG = {
+    silenceWarningMs: 120_000, // 2 minutes
+    silenceTerminateMs: 300_000, // 5 minutes
+    checkIntervalMs: 15_000, // 15 seconds
+    taskDescription: "",
+    taskKeywords: [],
+    maxDriftWarnings: 3,
+};
+// ---------------------------------------------------------------------------
+// Heartbeat persistence
+// ---------------------------------------------------------------------------
+function persistPulse(pulse) {
+    try {
+        ensureBrainFileSync(HEARTBEAT_FILE, SCHEMA_LINE);
+        appendBrainLineSync(HEARTBEAT_FILE, JSON.stringify(pulse));
+    }
+    catch (err) {
+        log.warn("Failed to persist heartbeat pulse", {
+            taskId: pulse.taskId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Keyword extraction for drift detection
+// ---------------------------------------------------------------------------
+/** Extract meaningful keywords from a task description. */
+export function extractTaskKeywords(description) {
+    // Remove common stop words and short words, keep meaningful terms
+    const stopWords = new Set([
+        "the", "a", "an", "and", "or", "but", "in", "on", "at", "to", "for",
+        "of", "with", "by", "from", "is", "are", "was", "were", "be", "been",
+        "being", "have", "has", "had", "do", "does", "did", "will", "would",
+        "could", "should", "may", "might", "shall", "can", "this", "that",
+        "these", "those", "it", "its", "not", "no", "all", "any", "each",
+        "every", "if", "then", "else", "when", "where", "how", "what", "which",
+        "who", "whom", "why", "so", "as", "up", "out", "about", "into", "over",
+        "after", "before", "between", "under", "above", "below", "just", "also",
+        "very", "too", "only", "own", "same", "than", "other", "such", "more",
+        "most", "some", "make", "use", "get", "set", "add", "run", "file",
+    ]);
+    return description
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !stopWords.has(w))
+        .slice(0, 20); // Cap at 20 keywords
+}
+// ---------------------------------------------------------------------------
+// Simple drift heuristic
+// ---------------------------------------------------------------------------
+/**
+ * Score how relevant an action summary is to the original task.
+ * Returns 0.0 (no overlap) to 1.0 (perfect overlap).
+ * Uses simple keyword overlap — not semantic, but fast and transparent.
+ */
+function driftScore(actionSummary, taskKeywords) {
+    if (taskKeywords.length === 0)
+        return 1.0; // No keywords = no drift detection
+    const actionWords = new Set(actionSummary
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2));
+    let matches = 0;
+    for (const kw of taskKeywords) {
+        if (actionWords.has(kw))
+            matches++;
+    }
+    return matches / taskKeywords.length;
+}
+// ---------------------------------------------------------------------------
+// HeartbeatTracker — per-agent instance
+// ---------------------------------------------------------------------------
+export class HeartbeatTracker {
+    taskId;
+    instanceId;
+    config;
+    onTerminate;
+    lastPulseAt;
+    driftWarnings = 0;
+    totalPulses = 0;
+    checkTimer = null;
+    terminated = false;
+    traceId;
+    constructor(taskId, instanceId, config, onTerminate) {
+        this.taskId = taskId;
+        this.instanceId = instanceId;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.onTerminate = onTerminate;
+        this.lastPulseAt = Date.now();
+        this.traceId = generateTraceId();
+        // If task description provided but no keywords, extract them
+        if (this.config.taskDescription && this.config.taskKeywords.length === 0) {
+            this.config.taskKeywords = extractTaskKeywords(this.config.taskDescription);
+        }
+    }
+    /** Start monitoring the agent's heartbeat. */
+    start() {
+        if (this.checkTimer)
+            return;
+        this.recordPulse("spawn", "Agent spawned, heartbeat tracking started");
+        this.checkTimer = setInterval(() => {
+            this.check();
+        }, this.config.checkIntervalMs);
+        log.info("Heartbeat tracking started", {
+            taskId: this.taskId,
+            instanceId: this.instanceId,
+            keywords: this.config.taskKeywords.slice(0, 5),
+        });
+    }
+    /** Stop monitoring (call on agent completion). */
+    stop(reason = "complete") {
+        if (this.checkTimer) {
+            clearInterval(this.checkTimer);
+            this.checkTimer = null;
+        }
+        this.recordPulse(reason, `Heartbeat tracking stopped: ${reason}`);
+        log.info("Heartbeat tracking stopped", {
+            taskId: this.taskId,
+            instanceId: this.instanceId,
+            reason,
+            totalPulses: this.totalPulses,
+            driftWarnings: this.driftWarnings,
+        });
+    }
+    /**
+     * Record a heartbeat pulse. Call this whenever the agent produces
+     * observable output (file write, stdout, checkpoint).
+     */
+    recordPulse(type, detail, actionSummary) {
+        if (this.terminated)
+            return;
+        this.lastPulseAt = Date.now();
+        this.totalPulses++;
+        const pulse = {
+            timestamp: new Date().toISOString(),
+            taskId: this.taskId,
+            instanceId: this.instanceId,
+            type,
+            detail,
+            actionSummary,
+        };
+        persistPulse(pulse);
+        // Drift detection on action pulses
+        if (type === "action" && actionSummary && this.config.taskKeywords.length > 0) {
+            const score = driftScore(actionSummary, this.config.taskKeywords);
+            if (score < 0.1) {
+                this.driftWarnings++;
+                log.warn("Drift detected", {
+                    taskId: this.taskId,
+                    instanceId: this.instanceId,
+                    score,
+                    actionSummary: actionSummary.slice(0, 100),
+                    driftWarnings: this.driftWarnings,
+                    maxDriftWarnings: this.config.maxDriftWarnings,
+                });
+                logActivity({
+                    source: "agent",
+                    summary: `Drift warning (${this.driftWarnings}/${this.config.maxDriftWarnings}): ${this.taskId}`,
+                    detail: `Score: ${score.toFixed(2)}, action: ${actionSummary.slice(0, 200)}`,
+                    traceId: this.traceId,
+                    actionLabel: "AUTONOMOUS",
+                    reason: "heartbeat-drift",
+                });
+                if (this.driftWarnings >= this.config.maxDriftWarnings) {
+                    this.terminateAgent(`Drift limit exceeded (${this.driftWarnings} warnings)`);
+                }
+            }
+            else if (score > 0.3) {
+                // Good signal — reset drift counter on clearly relevant actions
+                this.driftWarnings = Math.max(0, this.driftWarnings - 1);
+            }
+        }
+    }
+    /** Get the current heartbeat status. */
+    getStatus() {
+        const silenceMs = Date.now() - this.lastPulseAt;
+        let state = "healthy";
+        if (this.terminated) {
+            state = "terminated";
+        }
+        else if (silenceMs > this.config.silenceTerminateMs) {
+            state = "critical";
+        }
+        else if (silenceMs > this.config.silenceWarningMs ||
+            this.driftWarnings >= this.config.maxDriftWarnings - 1) {
+            state = "warning";
+        }
+        return {
+            taskId: this.taskId,
+            instanceId: this.instanceId,
+            alive: !this.terminated,
+            lastPulseAt: this.lastPulseAt ? new Date(this.lastPulseAt).toISOString() : null,
+            silenceMs,
+            driftWarnings: this.driftWarnings,
+            totalPulses: this.totalPulses,
+            state,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Internal
+    // -------------------------------------------------------------------------
+    check() {
+        if (this.terminated)
+            return;
+        const silenceMs = Date.now() - this.lastPulseAt;
+        if (silenceMs > this.config.silenceTerminateMs) {
+            this.terminateAgent(`Silence timeout: no activity for ${Math.round(silenceMs / 1000)}s ` +
+                `(limit: ${Math.round(this.config.silenceTerminateMs / 1000)}s)`);
+            return;
+        }
+        if (silenceMs > this.config.silenceWarningMs) {
+            this.recordPulse("silence-warning", `No activity for ${Math.round(silenceMs / 1000)}s`);
+            logActivity({
+                source: "agent",
+                summary: `Silence warning: ${this.taskId}`,
+                detail: `No activity for ${Math.round(silenceMs / 1000)}s`,
+                traceId: this.traceId,
+                actionLabel: "AUTONOMOUS",
+                reason: "heartbeat-silence",
+            });
+        }
+    }
+    terminateAgent(reason) {
+        if (this.terminated)
+            return;
+        this.terminated = true;
+        log.warn("Terminating agent via heartbeat", {
+            taskId: this.taskId,
+            instanceId: this.instanceId,
+            reason,
+        });
+        this.recordPulse("terminate", reason);
+        logActivity({
+            source: "agent",
+            summary: `Heartbeat termination: ${this.taskId}`,
+            detail: reason,
+            traceId: this.traceId,
+            actionLabel: "AUTONOMOUS",
+            reason: "heartbeat-terminate",
+        });
+        this.stop("terminate");
+        // Fire-and-forget termination callback
+        this.onTerminate(this.instanceId, reason).catch((err) => {
+            log.error("Failed to terminate agent", {
+                instanceId: this.instanceId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Tracker registry — manage all active heartbeat trackers
+// ---------------------------------------------------------------------------
+const activeTrackers = new Map();
+/** Create and register a heartbeat tracker for an agent instance. */
+export function createHeartbeatTracker(taskId, instanceId, config, onTerminate) {
+    // Clean up any existing tracker for this instance
+    const existing = activeTrackers.get(instanceId);
+    if (existing) {
+        existing.stop("terminate");
+    }
+    const tracker = new HeartbeatTracker(taskId, instanceId, config, onTerminate);
+    activeTrackers.set(instanceId, tracker);
+    return tracker;
+}
+/** Get a tracker by instance ID. */
+export function getHeartbeatTracker(instanceId) {
+    return activeTrackers.get(instanceId);
+}
+/** Remove a tracker (call on agent completion). */
+export function removeHeartbeatTracker(instanceId) {
+    const tracker = activeTrackers.get(instanceId);
+    if (tracker) {
+        tracker.stop();
+        activeTrackers.delete(instanceId);
+    }
+}
+/** Get status of all tracked agents. */
+export function getAllHeartbeatStatuses() {
+    return Array.from(activeTrackers.values()).map((t) => t.getStatus());
+}
+/** Stop all trackers (call on shutdown). */
+export function shutdownHeartbeats() {
+    for (const [id, tracker] of activeTrackers) {
+        tracker.stop("terminate");
+        activeTrackers.delete(id);
+    }
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/agents/heartbeat.js.map

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

package/dist/agents/index.d.ts

@@ -7,6 +7,9 @@ export { acquireLocks, releaseLocks, releaseFileLock, forceReleaseLock, listLock
 export { Orchestrator, parseFilesFromOutput, type WorkflowTaskDef, type CreateWorkflowInput, type Workflow, type WorkflowTask, type WorkflowResult, type WorkflowStatus, type TaskStatus, type FileConflict, type ConflictStrategy, type ExecutionMode, type OrchestratorReport, } from "./orchestration.js";
 export { TaskCooldownManager, type CooldownConfig, type CooldownEntry, type CooldownStatus, } from "./cooldown.js";
 export { WorkflowEngine, parseWorkflowFile, type WorkflowDefinition, type StepDef, type Condition, type FailurePolicy, type WorkflowRun, type StepResult, type StepStatus, } from "./workflow.js";
+export { governanceGate, revokeGovernanceVoucher, validateGovernanceVoucher, type GovernanceDecision, type GovernanceAuditEntry, type GovernanceOptions, } from "./governance.js";
+export { HeartbeatTracker, createHeartbeatTracker, getHeartbeatTracker, removeHeartbeatTracker, getAllHeartbeatStatuses, shutdownHeartbeats, extractTaskKeywords, type HeartbeatPulse, type HeartbeatConfig, type HeartbeatStatus, type TerminateCallback, } from "./heartbeat.js";
+export { governedSpawn, type GovernedSpawnRequest, type GovernedSpawnResult, type GovernedSpawnDeps, } from "./governed-spawn.js";
 import type { CreateTaskInput, AgentTask } from "./types.js";
 /** Create a task and immediately spawn it. */
 export declare function submitTask(input: CreateTaskInput): Promise<AgentTask>;
@@ -29,6 +32,6 @@ export declare function initAgents(): Promise<void>;
  * This prevents the double-recovery race that caused DASH-82.
  */
 export declare function recoverAndStartMonitor(): Promise<void>;
-/** Shutdown: stop the monitor. Does NOT kill detached processes. */
+/** Shutdown: stop the monitor and heartbeat trackers. Does NOT kill detached processes. */
 export declare function shutdownAgents(): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/agents/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC9E,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,EACL,UAAU,EACV,UAAU,EACV,QAAQ,EACR,SAAS,EACT,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACzH,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAK7D,8CAA8C;AAC9C,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CAI3E;AAED,+BAA+B;AAC/B,wBAAsB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAEnE;AAED,oCAAoC;AACpC,wBAAsB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE/D;AAED,6BAA6B;AAC7B,wBAAsB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE7D;AAED;;;;GAIG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAEhD;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAG5D;AAED,oEAAoE;AACpE,wBAAgB,cAAc,IAAI,IAAI,CAErC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC9E,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,EACL,UAAU,EACV,UAAU,EACV,QAAQ,EACR,SAAS,EACT,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACzH,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,yBAAyB,EACzB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,GACvB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAM7D,8CAA8C;AAC9C,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CAI3E;AAED,+BAA+B;AAC/B,wBAAsB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAEnE;AAED,oCAAoC;AACpC,wBAAsB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE/D;AAED,6BAA6B;AAC7B,wBAAsB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE7D;AAED;;;;GAIG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAEhD;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAG5D;AAED,2FAA2F;AAC3F,wBAAgB,cAAc,IAAI,IAAI,CAGrC"}

package/dist/agents/index.js

@@ -5,9 +5,13 @@ export { acquireLocks, releaseLocks, releaseFileLock, forceReleaseLock, listLock
 export { Orchestrator, parseFilesFromOutput, } from "./orchestration.js";
 export { TaskCooldownManager, } from "./cooldown.js";
 export { WorkflowEngine, parseWorkflowFile, } from "./workflow.js";
+export { governanceGate, revokeGovernanceVoucher, validateGovernanceVoucher, } from "./governance.js";
+export { HeartbeatTracker, createHeartbeatTracker, getHeartbeatTracker, removeHeartbeatTracker, getAllHeartbeatStatuses, shutdownHeartbeats, extractTaskKeywords, } from "./heartbeat.js";
+export { governedSpawn, } from "./governed-spawn.js";
 import { ensureDirs, createTask, readTask, readTaskOutput } from "./store.js";
 import { spawnAgent, cancelAgent } from "./spawn.js";
 import { recoverTasks, startAgentMonitor, stopAgentMonitor } from "./monitor.js";
+import { shutdownHeartbeats } from "./heartbeat.js";
 /** Create a task and immediately spawn it. */
 export async function submitTask(input) {
     const task = await createTask(input);
@@ -44,8 +48,9 @@ export async function recoverAndStartMonitor() {
     await recoverTasks();
     startAgentMonitor();
 }
-/** Shutdown: stop the monitor. Does NOT kill detached processes. */
+/** Shutdown: stop the monitor and heartbeat trackers. Does NOT kill detached processes. */
 export function shutdownAgents() {
     stopAgentMonitor();
+    shutdownHeartbeats();
 }
 //# sourceMappingURL=index.js.map

package/dist/agents/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,UAAU,EACV,UAAU,EACV,QAAQ,EACR,SAAS,EACT,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACzH,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,kBAAkB,GAInB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,EACZ,oBAAoB,GAYrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,mBAAmB,GAIpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,iBAAiB,GAQlB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAA6B,cAAc,EAAE,MAAM,YAAY,CAAC;AACzG,OAAO,EAAE,UAAU,EAAE,WAAW,EAAgB,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEjF,8CAA8C;AAC9C,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAsB;IACrD,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,CAAC;IACrC,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+BAA+B;AAC/B,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,EAAU;IACtC,OAAO,QAAQ,CAAC,EAAE,CAAC,CAAC;AACtB,CAAC;AAED,oCAAoC;AACpC,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAAU;IAC5C,OAAO,cAAc,CAAC,EAAE,CAAC,CAAC;AAC5B,CAAC;AAED,6BAA6B;AAC7B,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,EAAU;IACzC,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,MAAM,UAAU,EAAE,CAAC;AACrB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB;IAC1C,MAAM,YAAY,EAAE,CAAC;IACrB,iBAAiB,EAAE,CAAC;AACtB,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,cAAc;IAC5B,gBAAgB,EAAE,CAAC;AACrB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,UAAU,EACV,UAAU,EACV,QAAQ,EACR,SAAS,EACT,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACzH,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,kBAAkB,GAInB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,YAAY,EACZ,oBAAoB,GAYrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,mBAAmB,GAIpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,iBAAiB,GAQlB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,yBAAyB,GAI1B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,mBAAmB,GAKpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,aAAa,GAId,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAA6B,cAAc,EAAE,MAAM,YAAY,CAAC;AACzG,OAAO,EAAE,UAAU,EAAE,WAAW,EAAgB,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,8CAA8C;AAC9C,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAsB;IACrD,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,CAAC;IACrC,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+BAA+B;AAC/B,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,EAAU;IACtC,OAAO,QAAQ,CAAC,EAAE,CAAC,CAAC;AACtB,CAAC;AAED,oCAAoC;AACpC,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAAU;IAC5C,OAAO,cAAc,CAAC,EAAE,CAAC,CAAC;AAC5B,CAAC;AAED,6BAA6B;AAC7B,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,EAAU;IACzC,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,MAAM,UAAU,EAAE,CAAC;AACrB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB;IAC1C,MAAM,YAAY,EAAE,CAAC;IACrB,iBAAiB,EAAE,CAAC;AACtB,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,cAAc;IAC5B,gBAAgB,EAAE,CAAC;IACnB,kBAAkB,EAAE,CAAC;AACvB,CAAC"}

package/dist/agents/spawn-policy.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Spawn Policy Loader — governs what agent types can be spawned and how many.
+ *
+ * Reads brain/templates/spawn-policy.yaml (or instance-specific path).
+ * Provides checkSpawnPolicy() for the governance gate to call before spawn.
+ *
+ * Hand-rolled YAML parser (no external deps).
+ */
+export interface AllowedType {
+    max: number;
+    autoSpawn: boolean;
+}
+export interface SpawnPolicy {
+    owner: string;
+    governedBy: string;
+    maxAgents: number;
+    allowedTypes: Map<string, AllowedType>;
+    denyTypes: string[];
+    requireOwnerApproval: boolean;
+}
+export interface SpawnPolicyCheck {
+    allowed: boolean;
+    reason?: string;
+}
+/**
+ * Load and cache the spawn policy.
+ */
+export declare function loadSpawnPolicy(policyPath?: string): Promise<SpawnPolicy>;
+/**
+ * Get the cached spawn policy (loads synchronously if not cached).
+ */
+export declare function getSpawnPolicy(): SpawnPolicy;
+/**
+ * Check whether spawning an agent of the given type is allowed.
+ *
+ * @param agentType   - The agent type to spawn (e.g. "administration", "brand")
+ * @param currentCount - Total number of currently running agents
+ * @param typeCount    - Number of currently running agents of this specific type
+ */
+export declare function checkSpawnPolicy(agentType: string, currentCount: number, typeCount: number): SpawnPolicyCheck;
+/**
+ * Force reload of spawn policy.
+ */
+export declare function reloadSpawnPolicy(policyPath?: string): Promise<SpawnPolicy>;
+//# sourceMappingURL=spawn-policy.d.ts.map

package/dist/agents/spawn-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-policy.d.ts","sourceRoot":"","sources":["../../src/agents/spawn-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAcH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACvC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmGD;;GAEG;AACH,wBAAsB,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA2B/E;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAsB5C;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAyBlB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAGjF"}

package/dist/agents/spawn-policy.js

@@ -0,0 +1,202 @@
+/**
+ * Spawn Policy Loader — governs what agent types can be spawned and how many.
+ *
+ * Reads brain/templates/spawn-policy.yaml (or instance-specific path).
+ * Provides checkSpawnPolicy() for the governance gate to call before spawn.
+ *
+ * Hand-rolled YAML parser (no external deps).
+ */
+import { readFile } from "node:fs/promises";
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createLogger } from "../utils/logger.js";
+const log = createLogger("agents.spawn-policy");
+const BRAIN_DIR = resolve(process.cwd(), "brain");
+const DEFAULT_POLICY_PATH = join(BRAIN_DIR, "templates", "spawn-policy.yaml");
+// ── Cache ────────────────────────────────────────────────────────────────────
+let cached = null;
+// ── YAML parser ──────────────────────────────────────────────────────────────
+function parseSpawnPolicy(raw) {
+    const lines = raw.split("\n");
+    let owner = "";
+    let governedBy = "";
+    let maxAgents = 4;
+    let requireOwnerApproval = true;
+    const allowedTypes = new Map();
+    const denyTypes = [];
+    let section = "root";
+    let currentType = "";
+    for (const line of lines) {
+        const trimmed = line.trimEnd();
+        if (!trimmed || trimmed.match(/^\s*#/))
+            continue;
+        const indent = (line.match(/^(\s*)/) ?? ["", ""])[1].length;
+        // Top-level key: value
+        if (indent === 0) {
+            const kv = trimmed.match(/^(\w[\w_]*)\s*:\s*(.+)$/);
+            if (kv) {
+                const [, key, val] = kv;
+                const unquoted = val.replace(/^["']|["']$/g, "").trim();
+                if (key === "owner")
+                    owner = unquoted;
+                else if (key === "governed_by")
+                    governedBy = unquoted;
+                else if (key === "max_agents")
+                    maxAgents = parseInt(unquoted, 10) || 4;
+                else if (key === "require_owner_approval")
+                    requireOwnerApproval = unquoted === "true";
+                section = "root";
+                continue;
+            }
+            // Section header
+            const sectionHeader = trimmed.match(/^(\w[\w_]*)\s*:\s*$/);
+            if (sectionHeader) {
+                if (sectionHeader[1] === "allowed_types")
+                    section = "allowed_types";
+                else if (sectionHeader[1] === "deny_types")
+                    section = "deny_types";
+                else
+                    section = "root";
+                continue;
+            }
+        }
+        // Under allowed_types — type name headers (indent 2)
+        if (section === "allowed_types" && indent >= 2) {
+            const typeHeader = trimmed.trim().match(/^([\w-]+)\s*:\s*$/);
+            if (typeHeader) {
+                currentType = typeHeader[1];
+                allowedTypes.set(currentType, { max: 1, autoSpawn: false });
+                section = "allowed_type_entry";
+                continue;
+            }
+        }
+        // Under a specific allowed type entry (indent 4)
+        if (section === "allowed_type_entry" && indent >= 4) {
+            const kv = trimmed.trim().match(/^(\w[\w_]*)\s*:\s*(.+)$/);
+            if (kv) {
+                const [, key, val] = kv;
+                const entry = allowedTypes.get(currentType);
+                if (entry) {
+                    if (key === "max")
+                        entry.max = parseInt(val, 10) || 1;
+                    else if (key === "auto_spawn")
+                        entry.autoSpawn = val.trim() === "true";
+                }
+                continue;
+            }
+            // New type header at indent 2 — go back to allowed_types
+            const typeHeader = trimmed.trim().match(/^([\w-]+)\s*:\s*$/);
+            if (typeHeader) {
+                currentType = typeHeader[1];
+                allowedTypes.set(currentType, { max: 1, autoSpawn: false });
+                continue;
+            }
+        }
+        // deny_types list items
+        if (section === "deny_types") {
+            const listItem = trimmed.match(/^\s+-\s+(.+)$/);
+            if (listItem) {
+                denyTypes.push(listItem[1].replace(/^["']|["']$/g, "").trim());
+            }
+        }
+    }
+    return { owner, governedBy, maxAgents, allowedTypes, denyTypes, requireOwnerApproval };
+}
+// ── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Load and cache the spawn policy.
+ */
+export async function loadSpawnPolicy(policyPath) {
+    if (cached)
+        return cached;
+    const filePath = policyPath ?? DEFAULT_POLICY_PATH;
+    try {
+        const raw = await readFile(filePath, "utf-8");
+        cached = parseSpawnPolicy(raw);
+        log.info("Spawn policy loaded", {
+            maxAgents: cached.maxAgents,
+            allowedTypes: Array.from(cached.allowedTypes.keys()),
+            denyTypes: cached.denyTypes,
+        });
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            log.warn("No spawn-policy.yaml found — using permissive defaults");
+        }
+        else {
+            log.warn("Failed to parse spawn-policy.yaml", { error: err.message });
+        }
+        cached = {
+            owner: "",
+            governedBy: "",
+            maxAgents: 4,
+            allowedTypes: new Map(),
+            denyTypes: [],
+            requireOwnerApproval: false,
+        };
+    }
+    return cached;
+}
+/**
+ * Get the cached spawn policy (loads synchronously if not cached).
+ */
+export function getSpawnPolicy() {
+    if (!cached) {
+        try {
+            if (existsSync(DEFAULT_POLICY_PATH)) {
+                const raw = readFileSync(DEFAULT_POLICY_PATH, "utf-8");
+                cached = parseSpawnPolicy(raw);
+            }
+        }
+        catch {
+            // Fall through to defaults
+        }
+        if (!cached) {
+            cached = {
+                owner: "",
+                governedBy: "",
+                maxAgents: 4,
+                allowedTypes: new Map(),
+                denyTypes: [],
+                requireOwnerApproval: false,
+            };
+        }
+    }
+    return cached;
+}
+/**
+ * Check whether spawning an agent of the given type is allowed.
+ *
+ * @param agentType   - The agent type to spawn (e.g. "administration", "brand")
+ * @param currentCount - Total number of currently running agents
+ * @param typeCount    - Number of currently running agents of this specific type
+ */
+export function checkSpawnPolicy(agentType, currentCount, typeCount) {
+    const policy = getSpawnPolicy();
+    // Check deny list
+    if (policy.denyTypes.includes(agentType)) {
+        return { allowed: false, reason: `Agent type "${agentType}" is denied by spawn policy` };
+    }
+    // Check global max
+    if (currentCount >= policy.maxAgents) {
+        return { allowed: false, reason: `Max agents reached (${policy.maxAgents})` };
+    }
+    // Check type-specific max
+    const typeConfig = policy.allowedTypes.get(agentType);
+    if (typeConfig && typeCount >= typeConfig.max) {
+        return { allowed: false, reason: `Max "${agentType}" agents reached (${typeConfig.max})` };
+    }
+    // If the type isn't in allowed_types and the map is non-empty, it's implicitly denied
+    if (policy.allowedTypes.size > 0 && !typeConfig) {
+        return { allowed: false, reason: `Agent type "${agentType}" is not in allowed_types` };
+    }
+    return { allowed: true };
+}
+/**
+ * Force reload of spawn policy.
+ */
+export async function reloadSpawnPolicy(policyPath) {
+    cached = null;
+    return loadSpawnPolicy(policyPath);
+}
+//# sourceMappingURL=spawn-policy.js.map