@runcore-sh/runcore 0.1.7 → 0.1.9

package/dist/agents/governance.js

@@ -0,0 +1,220 @@
+/**
+ * Agent Governance Gate — CORE-9
+ *
+ * Pre-spawn validation that replaces the `--dangerously-skip-permissions`
+ * prompt with voucher-based authorization, locked-path enforcement, and
+ * principle injection.
+ *
+ * Every governed spawn:
+ * 1. Issues a scoped voucher for the task
+ * 2. Reads locked paths and builds a deny-list for the agent's prompt
+ * 3. Injects core principles as behavioral constraints
+ * 4. Wraps the prompt with governance preamble
+ * 5. Logs the governance decision to the audit trail
+ */
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { issueVoucher, checkVoucher, revokeVoucher } from "../voucher.js";
+import { loadLockedPaths } from "../lib/locked.js";
+import { checkSpawnPolicy, loadSpawnPolicy } from "./spawn-policy.js";
+import { logActivity } from "../activity/log.js";
+import { createLogger } from "../utils/logger.js";
+const log = createLogger("governance");
+const BRAIN_DIR = resolve(process.cwd(), "brain");
+// ---------------------------------------------------------------------------
+// Governance preamble components
+// ---------------------------------------------------------------------------
+function buildLockedPathsSection(paths) {
+    if (paths.length === 0)
+        return "";
+    const pathList = paths.map((p) => `  - brain/${p}`).join("\n");
+    return `
+## Locked Paths (DO NOT ACCESS)
+The following paths are locked by governance policy. Do NOT read, write, or
+reference these files. Violations will be logged and may terminate your session.
+
+${pathList}
+`;
+}
+function buildVoucherSection(token, scope) {
+    return `
+## Governance Voucher
+You are operating under voucher \`${token}\` with scope \`${scope}\`.
+This voucher is time-limited. If you receive a governance violation, stop immediately.
+`;
+}
+async function loadPrinciples() {
+    try {
+        const principlesPath = join(BRAIN_DIR, "identity", "principles.md");
+        const content = await readFile(principlesPath, "utf-8");
+        // Extract just the key principles, not the full document
+        const lines = content.split("\n");
+        const keyPrinciples = [];
+        for (const line of lines) {
+            if (line.startsWith("**") && line.endsWith("**")) {
+                keyPrinciples.push(line);
+            }
+        }
+        if (keyPrinciples.length === 0)
+            return "";
+        return `
+## Operating Principles
+You must adhere to these principles during execution:
+${keyPrinciples.map((p) => `- ${p}`).join("\n")}
+`;
+    }
+    catch {
+        log.warn("Could not load principles — proceeding without them");
+        return "";
+    }
+}
+// ---------------------------------------------------------------------------
+// Main governance gate
+// ---------------------------------------------------------------------------
+/**
+ * Run the governance gate before spawning an agent.
+ * Returns a GovernanceDecision with the governed prompt (or denial).
+ */
+export async function governanceGate(opts) {
+    const { taskId, label, prompt, origin, ltm, scope: scopeOverride, voucherTtlMinutes = 30, skipVoucher = false, } = opts;
+    const scope = scopeOverride ?? `agent:spawn:${taskId}`;
+    const timestamp = new Date().toISOString();
+    // 1. Load locked paths
+    const lockedPaths = await loadLockedPaths();
+    // 1b. Spawn policy check (if agentType provided)
+    if (opts.agentType) {
+        await loadSpawnPolicy();
+        const spawnCheck = checkSpawnPolicy(opts.agentType, opts.currentAgentCount ?? 0, opts.currentTypeCount ?? 0);
+        if (!spawnCheck.allowed) {
+            const reason = `Spawn policy denied: ${spawnCheck.reason}`;
+            log.warn(reason, { taskId, agentType: opts.agentType });
+            const auditEntry = {
+                timestamp,
+                taskId,
+                label,
+                decision: "deny",
+                lockedPathCount: lockedPaths.length,
+                reason,
+            };
+            logActivity({
+                source: "agent",
+                summary: `Governance DENIED (spawn policy): ${label}`,
+                detail: reason,
+                actionLabel: origin === "ai" ? "AUTONOMOUS" : "PROMPTED",
+                reason: "governance-gate",
+            });
+            return {
+                allowed: false,
+                deniedReason: reason,
+                governedPrompt: prompt,
+                lockedPaths,
+                auditEntry,
+            };
+        }
+    }
+    // 2. Issue voucher (unless skipped for system tasks)
+    let voucherToken;
+    if (!skipVoucher) {
+        try {
+            voucherToken = await issueVoucher(ltm, scope, voucherTtlMinutes);
+            log.info("Voucher issued for agent", { taskId, token: voucherToken, scope });
+        }
+        catch (err) {
+            const reason = `Voucher issuance failed: ${err instanceof Error ? err.message : String(err)}`;
+            log.error(reason, { taskId });
+            const auditEntry = {
+                timestamp,
+                taskId,
+                label,
+                decision: "deny",
+                lockedPathCount: lockedPaths.length,
+                reason,
+            };
+            logActivity({
+                source: "agent",
+                summary: `Governance DENIED: ${label}`,
+                detail: reason,
+                actionLabel: origin === "ai" ? "AUTONOMOUS" : "PROMPTED",
+                reason: "governance-gate",
+            });
+            return {
+                allowed: false,
+                deniedReason: reason,
+                governedPrompt: prompt,
+                lockedPaths,
+                auditEntry,
+            };
+        }
+    }
+    // 3. Load principles
+    const principlesSection = await loadPrinciples();
+    // 4. Build governed prompt
+    const governancePreamble = [
+        "## Governance Context",
+        "This agent session is governed by the Core orchestration system.",
+        "You are running with `--dangerously-skip-permissions`. In exchange,",
+        "governance controls replace the permission prompt. Violating these",
+        "controls will terminate your session.",
+        "",
+        voucherToken ? buildVoucherSection(voucherToken, scope) : "",
+        buildLockedPathsSection(lockedPaths),
+        principlesSection,
+        "## Heartbeat Requirement",
+        "Your actions are monitored. Extended silence (no file writes, no output)",
+        "will trigger a timeout and termination. Stay on task.",
+        "",
+        "---",
+        "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const governedPrompt = governancePreamble + prompt;
+    // 5. Log the decision
+    const auditEntry = {
+        timestamp,
+        taskId,
+        label,
+        decision: "allow",
+        voucherToken,
+        voucherScope: scope,
+        lockedPathCount: lockedPaths.length,
+    };
+    logActivity({
+        source: "agent",
+        summary: `Governance ALLOWED: ${label}`,
+        detail: `Voucher: ${voucherToken ?? "skipped"}, locked paths: ${lockedPaths.length}`,
+        actionLabel: origin === "ai" ? "AUTONOMOUS" : "PROMPTED",
+        reason: "governance-gate",
+    });
+    log.info("Governance gate passed", { taskId, label, voucherToken });
+    return {
+        allowed: true,
+        voucherToken,
+        governedPrompt,
+        lockedPaths,
+        auditEntry,
+    };
+}
+/**
+ * Revoke a governance voucher (call on agent completion or termination).
+ */
+export async function revokeGovernanceVoucher(ltm, token) {
+    try {
+        await revokeVoucher(ltm, token);
+        log.info("Governance voucher revoked", { token });
+    }
+    catch (err) {
+        log.warn("Failed to revoke voucher", {
+            token,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+/**
+ * Validate that a voucher is still active (for mid-session checks).
+ */
+export async function validateGovernanceVoucher(ltm, token) {
+    const result = await checkVoucher(ltm, token);
+    return result.valid;
+}
+//# sourceMappingURL=governance.js.map

package/dist/agents/governance.js.map

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

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

@@ -0,0 +1,83 @@
+/**
+ * Governed Agent Spawn — CORE-9
+ *
+ * High-level entry point for spawning Claude Code agents with full
+ * governance controls. Composes:
+ *
+ * 1. Governance gate (voucher + locked paths + principles)
+ * 2. Agent spawning (via existing pool or direct spawn)
+ * 3. Heartbeat monitoring (silence + drift detection)
+ * 4. Lifecycle management (cleanup on completion/termination)
+ *
+ * This replaces raw `--dangerously-skip-permissions` with a governed
+ * equivalent where vouchers, locked paths, and principles replace the
+ * interactive permission prompt.
+ */
+import type { LongTermMemoryStore } from "../memory/long-term.js";
+import type { AgentPool } from "./runtime.js";
+import type { AgentInstance } from "./runtime/types.js";
+import { type GovernanceDecision } from "./governance.js";
+import { type HeartbeatConfig, type HeartbeatTracker } from "./heartbeat.js";
+/** Input for a governed agent spawn. */
+export interface GovernedSpawnRequest {
+    /** Task identifier (should be unique). */
+    taskId: string;
+    /** Human-readable label. */
+    label: string;
+    /** The actual task prompt. */
+    prompt: string;
+    /** Working directory for the agent. */
+    cwd?: string;
+    /** Who initiated the spawn. */
+    origin: "user" | "ai" | "system";
+    /** Tags for grouping/filtering. */
+    tags?: string[];
+    /** Parent agent ID (for sub-agent spawns). */
+    parentId?: string;
+    /** Override heartbeat config. */
+    heartbeat?: Partial<HeartbeatConfig>;
+    /** Override voucher TTL (minutes). */
+    voucherTtlMinutes?: number;
+    /** Skip voucher for system-level tasks. */
+    skipVoucher?: boolean;
+    /** Agent type for spawn policy checks (e.g. "administration", "brand"). */
+    agentType?: string;
+    /** Current total running agent count (for spawn policy max check). */
+    currentAgentCount?: number;
+    /** Current running count of this specific agent type. */
+    currentTypeCount?: number;
+}
+/** Result of a governed spawn — includes governance metadata. */
+export interface GovernedSpawnResult {
+    /** Whether the spawn was allowed and succeeded. */
+    success: boolean;
+    /** The spawned agent instance (if successful). */
+    instance?: AgentInstance;
+    /** Governance decision details. */
+    governance: GovernanceDecision;
+    /** Heartbeat tracker (if spawn succeeded). */
+    heartbeat?: HeartbeatTracker;
+    /** Trace ID linking all activity for this spawn. */
+    traceId: string;
+    /** Denial reason (if not allowed). */
+    deniedReason?: string;
+}
+/** Dependencies injected into the governed spawn system. */
+export interface GovernedSpawnDeps {
+    /** Long-term memory store for voucher operations. */
+    ltm: LongTermMemoryStore;
+    /** Agent pool for spawning (preferred). */
+    pool?: AgentPool;
+}
+/**
+ * Spawn a Claude Code agent with full governance controls.
+ *
+ * Flow:
+ * 1. Run governance gate (voucher + locked paths + principles)
+ * 2. If denied → return failure with reason
+ * 3. Spawn agent via pool with governed prompt
+ * 4. Attach heartbeat tracker
+ * 5. Wire lifecycle cleanup (voucher revocation on exit)
+ */
+export declare function governedSpawn(request: GovernedSpawnRequest, deps: GovernedSpawnDeps): Promise<GovernedSpawnResult>;
+//# sourceMappingURL=governed-spawn.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"governed-spawn.d.ts","sourceRoot":"","sources":["../../src/agents/governed-spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAgB,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAIL,KAAK,kBAAkB,EAExB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,gBAAgB,CAAC;AAUxB,wCAAwC;AACxC,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,QAAQ,CAAC;IACjC,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACrC,sCAAsC;IACtC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,mCAAmC;IACnC,UAAU,EAAE,kBAAkB,CAAC;IAC/B,8CAA8C;IAC9C,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,GAAG,EAAE,mBAAmB,CAAC;IACzB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAMD;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,mBAAmB,CAAC,CA+K9B"}

package/dist/agents/governed-spawn.js

@@ -0,0 +1,186 @@
+/**
+ * Governed Agent Spawn — CORE-9
+ *
+ * High-level entry point for spawning Claude Code agents with full
+ * governance controls. Composes:
+ *
+ * 1. Governance gate (voucher + locked paths + principles)
+ * 2. Agent spawning (via existing pool or direct spawn)
+ * 3. Heartbeat monitoring (silence + drift detection)
+ * 4. Lifecycle management (cleanup on completion/termination)
+ *
+ * This replaces raw `--dangerously-skip-permissions` with a governed
+ * equivalent where vouchers, locked paths, and principles replace the
+ * interactive permission prompt.
+ */
+import { governanceGate, revokeGovernanceVoucher, } from "./governance.js";
+import { createHeartbeatTracker, removeHeartbeatTracker, extractTaskKeywords, } from "./heartbeat.js";
+import { logActivity, generateTraceId } from "../activity/log.js";
+import { createLogger } from "../utils/logger.js";
+const log = createLogger("governed-spawn");
+// ---------------------------------------------------------------------------
+// Governed spawn
+// ---------------------------------------------------------------------------
+/**
+ * Spawn a Claude Code agent with full governance controls.
+ *
+ * Flow:
+ * 1. Run governance gate (voucher + locked paths + principles)
+ * 2. If denied → return failure with reason
+ * 3. Spawn agent via pool with governed prompt
+ * 4. Attach heartbeat tracker
+ * 5. Wire lifecycle cleanup (voucher revocation on exit)
+ */
+export async function governedSpawn(request, deps) {
+    const traceId = generateTraceId();
+    const { ltm, pool } = deps;
+    log.info("Governed spawn requested", {
+        taskId: request.taskId,
+        label: request.label,
+        origin: request.origin,
+        traceId,
+    });
+    // 1. Run governance gate
+    const govOpts = {
+        taskId: request.taskId,
+        label: request.label,
+        prompt: request.prompt,
+        origin: request.origin,
+        ltm,
+        voucherTtlMinutes: request.voucherTtlMinutes,
+        skipVoucher: request.skipVoucher,
+        agentType: request.agentType,
+        currentAgentCount: request.currentAgentCount,
+        currentTypeCount: request.currentTypeCount,
+    };
+    const governance = await governanceGate(govOpts);
+    // 2. Check governance decision
+    if (!governance.allowed) {
+        log.warn("Governed spawn denied", {
+            taskId: request.taskId,
+            reason: governance.deniedReason,
+            traceId,
+        });
+        return {
+            success: false,
+            governance,
+            traceId,
+            deniedReason: governance.deniedReason,
+        };
+    }
+    // 3. Spawn agent via pool
+    if (!pool) {
+        const reason = "No agent pool available — cannot spawn governed agent";
+        log.error(reason, { taskId: request.taskId });
+        // Revoke the voucher since we can't use it
+        if (governance.voucherToken) {
+            await revokeGovernanceVoucher(ltm, governance.voucherToken);
+        }
+        return {
+            success: false,
+            governance,
+            traceId,
+            deniedReason: reason,
+        };
+    }
+    let instance;
+    try {
+        const spawnRequest = {
+            taskId: request.taskId,
+            label: request.label,
+            prompt: governance.governedPrompt,
+            cwd: request.cwd,
+            origin: request.origin,
+            tags: [
+                ...(request.tags ?? []),
+                "governed",
+                governance.voucherToken ? `voucher:${governance.voucherToken}` : "voucher:none",
+            ],
+            parentId: request.parentId,
+        };
+        instance = await pool.spawn(spawnRequest);
+        logActivity({
+            source: "agent",
+            summary: `Governed agent spawned: ${request.label}`,
+            detail: `Instance: ${instance.id}, PID: ${instance.pid}, voucher: ${governance.voucherToken ?? "none"}`,
+            traceId,
+            actionLabel: request.origin === "ai" ? "AUTONOMOUS" : "PROMPTED",
+            reason: "governed-spawn",
+        });
+    }
+    catch (err) {
+        const reason = `Spawn failed: ${err instanceof Error ? err.message : String(err)}`;
+        log.error(reason, { taskId: request.taskId, traceId });
+        // Revoke voucher on spawn failure
+        if (governance.voucherToken) {
+            await revokeGovernanceVoucher(ltm, governance.voucherToken);
+        }
+        return {
+            success: false,
+            governance,
+            traceId,
+            deniedReason: reason,
+        };
+    }
+    // 4. Attach heartbeat tracker
+    const taskKeywords = extractTaskKeywords(request.prompt);
+    const heartbeat = createHeartbeatTracker(request.taskId, instance.id, {
+        taskDescription: request.prompt,
+        taskKeywords,
+        ...request.heartbeat,
+    }, async (instanceId, reason) => {
+        // Termination callback from heartbeat
+        log.warn("Heartbeat triggered termination", { instanceId, reason, traceId });
+        try {
+            await pool.terminate(instanceId, reason);
+        }
+        catch (err) {
+            log.error("Failed to terminate via heartbeat", {
+                instanceId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    });
+    heartbeat.start();
+    // 5. Wire lifecycle cleanup via bus events
+    const cleanupHandler = async (event) => {
+        if (event.agentId !== instance.id)
+            return;
+        const terminalStates = new Set(["completed", "failed", "terminated"]);
+        if (!terminalStates.has(event.newState))
+            return;
+        // Remove handler
+        pool.runtimeManager.bus.off("agent:lifecycle", cleanupHandler);
+        // Stop heartbeat
+        removeHeartbeatTracker(instance.id);
+        // Revoke voucher
+        if (governance.voucherToken) {
+            await revokeGovernanceVoucher(ltm, governance.voucherToken);
+        }
+        logActivity({
+            source: "agent",
+            summary: `Governed agent ${event.newState}: ${request.label}`,
+            detail: `Instance: ${instance.id}, voucher revoked: ${governance.voucherToken ?? "none"}`,
+            traceId,
+            actionLabel: request.origin === "ai" ? "AUTONOMOUS" : "PROMPTED",
+            reason: "governed-lifecycle",
+        });
+    };
+    pool.runtimeManager.bus.on("agent:lifecycle", cleanupHandler);
+    log.info("Governed spawn complete", {
+        taskId: request.taskId,
+        instanceId: instance.id,
+        pid: instance.pid,
+        voucherToken: governance.voucherToken,
+        heartbeatKeywords: taskKeywords.slice(0, 5),
+        traceId,
+    });
+    return {
+        success: true,
+        instance,
+        governance,
+        heartbeat,
+        traceId,
+    };
+}
+//# sourceMappingURL=governed-spawn.js.map

package/dist/agents/governed-spawn.js.map

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

package/dist/agents/heartbeat.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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.
+ */
+/** A single heartbeat pulse from an agent. */
+export interface HeartbeatPulse {
+    timestamp: string;
+    taskId: string;
+    instanceId: string;
+    type: "spawn" | "action" | "output" | "checkpoint" | "complete" | "terminate" | "silence-warning";
+    detail?: string;
+    /** Semantic summary of what the agent is doing (for drift detection). */
+    actionSummary?: string;
+}
+/** Configuration for a heartbeat tracker. */
+export interface HeartbeatConfig {
+    /** Max silence before warning (ms). Default: 120_000 (2 min). */
+    silenceWarningMs: number;
+    /** Max silence before termination (ms). Default: 300_000 (5 min). */
+    silenceTerminateMs: number;
+    /** Check interval (ms). Default: 15_000 (15s). */
+    checkIntervalMs: number;
+    /** Task description for drift detection. */
+    taskDescription: string;
+    /** Keywords from the task for simple drift heuristic. */
+    taskKeywords: string[];
+    /** Max consecutive drift warnings before termination. Default: 3. */
+    maxDriftWarnings: number;
+}
+/** Status of a tracked agent's heartbeat. */
+export interface HeartbeatStatus {
+    taskId: string;
+    instanceId: string;
+    alive: boolean;
+    lastPulseAt: string | null;
+    silenceMs: number;
+    driftWarnings: number;
+    totalPulses: number;
+    state: "healthy" | "warning" | "critical" | "terminated";
+}
+/** Callback when an agent needs to be terminated. */
+export type TerminateCallback = (instanceId: string, reason: string) => Promise<void>;
+/** Extract meaningful keywords from a task description. */
+export declare function extractTaskKeywords(description: string): string[];
+export declare class HeartbeatTracker {
+    readonly taskId: string;
+    readonly instanceId: string;
+    private config;
+    private onTerminate;
+    private lastPulseAt;
+    private driftWarnings;
+    private totalPulses;
+    private checkTimer;
+    private terminated;
+    private traceId;
+    constructor(taskId: string, instanceId: string, config: Partial<HeartbeatConfig>, onTerminate: TerminateCallback);
+    /** Start monitoring the agent's heartbeat. */
+    start(): void;
+    /** Stop monitoring (call on agent completion). */
+    stop(reason?: "complete" | "terminate"): void;
+    /**
+     * Record a heartbeat pulse. Call this whenever the agent produces
+     * observable output (file write, stdout, checkpoint).
+     */
+    recordPulse(type: HeartbeatPulse["type"], detail?: string, actionSummary?: string): void;
+    /** Get the current heartbeat status. */
+    getStatus(): HeartbeatStatus;
+    private check;
+    private terminateAgent;
+}
+/** Create and register a heartbeat tracker for an agent instance. */
+export declare function createHeartbeatTracker(taskId: string, instanceId: string, config: Partial<HeartbeatConfig>, onTerminate: TerminateCallback): HeartbeatTracker;
+/** Get a tracker by instance ID. */
+export declare function getHeartbeatTracker(instanceId: string): HeartbeatTracker | undefined;
+/** Remove a tracker (call on agent completion). */
+export declare function removeHeartbeatTracker(instanceId: string): void;
+/** Get status of all tracked agents. */
+export declare function getAllHeartbeatStatuses(): HeartbeatStatus[];
+/** Stop all trackers (call on shutdown). */
+export declare function shutdownHeartbeats(): void;
+//# sourceMappingURL=heartbeat.d.ts.map

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

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