@a5c-ai/genty-platform 5.1.1-staging.00ceebd28cf2

package/dist/observability/promptPlan.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * Prompt plan capture and tracking (OBS-003).
+ *
+ * Records a planned sequence of steps before execution begins, then
+ * updates progress as each step completes. Useful for comparing the
+ * "intended plan" against what actually happened in a run.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.capturePromptPlan = capturePromptPlan;
+exports.updatePlanProgress = updatePlanProgress;
+exports.formatPlanSummary = formatPlanSummary;
+// ---------------------------------------------------------------------------
+// Capture
+// ---------------------------------------------------------------------------
+/**
+ * Create a new prompt plan from a list of step labels.
+ * All steps start in `pending` status.
+ */
+function capturePromptPlan(planId, title, stepLabels, now) {
+    const timestamp = now ?? new Date().toISOString();
+    return {
+        planId,
+        title,
+        steps: stepLabels.map((label, idx) => ({
+            id: `${planId}-step-${idx}`,
+            label,
+            status: 'pending',
+        })),
+        capturedAt: timestamp,
+        updatedAt: timestamp,
+    };
+}
+// ---------------------------------------------------------------------------
+// Progress updates
+// ---------------------------------------------------------------------------
+/**
+ * Update the status of a step within a plan. Returns a new PromptPlan
+ * (immutable update).
+ */
+function updatePlanProgress(plan, stepId, status, opts) {
+    const timestamp = opts?.now ?? new Date().toISOString();
+    return {
+        ...plan,
+        updatedAt: timestamp,
+        steps: plan.steps.map((step) => {
+            if (step.id !== stepId)
+                return step;
+            return {
+                ...step,
+                status,
+                startedAt: status === 'in-progress' ? (step.startedAt ?? timestamp) : step.startedAt,
+                completedAt: status === 'completed' || status === 'failed' || status === 'skipped'
+                    ? timestamp
+                    : step.completedAt,
+                error: status === 'failed' ? opts?.error : step.error,
+            };
+        }),
+    };
+}
+/**
+ * Produce a summary snapshot for a prompt plan.
+ */
+function formatPlanSummary(plan) {
+    const counts = {
+        pending: 0,
+        'in-progress': 0,
+        completed: 0,
+        skipped: 0,
+        failed: 0,
+    };
+    for (const step of plan.steps) {
+        counts[step.status]++;
+    }
+    const lines = [`Plan: ${plan.title} (${plan.planId})`];
+    for (const step of plan.steps) {
+        const icon = step.status === 'completed'
+            ? '[x]'
+            : step.status === 'failed'
+                ? '[!]'
+                : step.status === 'skipped'
+                    ? '[-]'
+                    : step.status === 'in-progress'
+                        ? '[>]'
+                        : '[ ]';
+        const suffix = step.error ? ` -- ${step.error}` : '';
+        lines.push(`  ${icon} ${step.label}${suffix}`);
+    }
+    lines.push(`Progress: ${counts.completed}/${plan.steps.length} completed, ${counts.failed} failed, ${counts.skipped} skipped`);
+    return {
+        planId: plan.planId,
+        title: plan.title,
+        total: plan.steps.length,
+        completed: counts.completed,
+        failed: counts.failed,
+        skipped: counts.skipped,
+        pending: counts.pending,
+        inProgress: counts['in-progress'],
+        formatted: lines.join('\n'),
+    };
+}

package/dist/observability/resumeDashboard.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Resume dashboard — build a summary view of a run's progress so
+ * operators can quickly see what completed, what's pending, and what
+ * failed before deciding to resume (GAP-UX-008).
+ */
+export interface StepSummary {
+    id: string;
+    title: string;
+    status: 'completed' | 'pending' | 'failed';
+}
+export interface ResumeDashboardData {
+    runId: string;
+    status: 'completed' | 'running' | 'failed' | 'paused';
+    completedSteps: StepSummary[];
+    pendingSteps: StepSummary[];
+    failedSteps: StepSummary[];
+    totalDuration: number;
+    lastActivity: string;
+}
+/**
+ * Read run state from disk and build dashboard data.
+ *
+ * Expects a run directory containing:
+ * - metadata.json  (runId, createdAt)
+ * - journal.jsonl  (events for timing/status)
+ */
+export declare function buildResumeDashboard(runDir: string): Promise<ResumeDashboardData>;
+/**
+ * Render dashboard data as a human-readable ASCII text block.
+ */
+export declare function formatDashboardText(data: ResumeDashboardData): string;
+//# sourceMappingURL=resumeDashboard.d.ts.map

package/dist/observability/resumeDashboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumeDashboard.d.ts","sourceRoot":"","sources":["../../src/observability/resumeDashboard.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACtD,cAAc,EAAE,WAAW,EAAE,CAAC;IAC9B,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,WAAW,EAAE,WAAW,EAAE,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAMD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA6FvF;AAiBD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAyCrE"}

package/dist/observability/resumeDashboard.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * Resume dashboard — build a summary view of a run's progress so
+ * operators can quickly see what completed, what's pending, and what
+ * failed before deciding to resume (GAP-UX-008).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildResumeDashboard = buildResumeDashboard;
+exports.formatDashboardText = formatDashboardText;
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+/**
+ * Read run state from disk and build dashboard data.
+ *
+ * Expects a run directory containing:
+ * - metadata.json  (runId, createdAt)
+ * - journal.jsonl  (events for timing/status)
+ */
+async function buildResumeDashboard(runDir) {
+    // Read metadata
+    const metaPath = path.join(runDir, 'metadata.json');
+    const metaRaw = await node_fs_1.promises.readFile(metaPath, 'utf-8');
+    const meta = JSON.parse(metaRaw);
+    // Read journal
+    const journalPath = path.join(runDir, 'journal.jsonl');
+    let journalLines = [];
+    try {
+        const journalRaw = await node_fs_1.promises.readFile(journalPath, 'utf-8');
+        journalLines = journalRaw.split('\n').filter((l) => l.trim().length > 0);
+    }
+    catch {
+        // journal may not exist yet
+    }
+    const events = [];
+    for (const line of journalLines) {
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            // skip malformed lines
+        }
+    }
+    // Classify effects into steps
+    const requested = new Map();
+    const resolved = new Set();
+    const failed = new Set();
+    for (const evt of events) {
+        const effectId = typeof evt.data?.effectId === 'string' ? evt.data.effectId : undefined;
+        if (!effectId)
+            continue;
+        if (evt.type === 'EFFECT_REQUESTED') {
+            requested.set(effectId, {
+                id: effectId,
+                title: typeof evt.data.title === 'string' ? evt.data.title : effectId,
+                requestedAt: evt.recordedAt,
+            });
+        }
+        if (evt.type === 'EFFECT_RESOLVED') {
+            resolved.add(effectId);
+        }
+        if (evt.type === 'EFFECT_FAILED') {
+            failed.add(effectId);
+        }
+    }
+    const completedSteps = [];
+    const pendingSteps = [];
+    const failedSteps = [];
+    for (const [effectId, info] of requested) {
+        if (failed.has(effectId)) {
+            failedSteps.push({ id: info.id, title: info.title, status: 'failed' });
+        }
+        else if (resolved.has(effectId)) {
+            completedSteps.push({ id: info.id, title: info.title, status: 'completed' });
+        }
+        else {
+            pendingSteps.push({ id: info.id, title: info.title, status: 'pending' });
+        }
+    }
+    // Derive overall status
+    const hasRunCompleted = events.some((e) => e.type === 'RUN_COMPLETED');
+    const hasRunFailed = events.some((e) => e.type === 'RUN_FAILED');
+    let status;
+    if (hasRunFailed || failedSteps.length > 0) {
+        status = 'failed';
+    }
+    else if (hasRunCompleted) {
+        status = 'completed';
+    }
+    else if (pendingSteps.length > 0) {
+        status = 'paused';
+    }
+    else {
+        status = 'running';
+    }
+    // Timing
+    const createdMs = new Date(meta.createdAt).getTime();
+    const lastEvent = events[events.length - 1];
+    const lastActivity = lastEvent?.recordedAt ?? meta.createdAt;
+    const lastMs = new Date(lastActivity).getTime();
+    const totalDuration = lastMs - createdMs;
+    return {
+        runId: meta.runId,
+        status,
+        completedSteps,
+        pendingSteps,
+        failedSteps,
+        totalDuration,
+        lastActivity,
+    };
+}
+// ---------------------------------------------------------------------------
+// Formatter
+// ---------------------------------------------------------------------------
+function formatDurationMs(ms) {
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remainSec = seconds % 60;
+    if (minutes < 60)
+        return `${minutes}m ${remainSec}s`;
+    const hours = Math.floor(minutes / 60);
+    const remainMin = minutes % 60;
+    return `${hours}h ${remainMin}m`;
+}
+/**
+ * Render dashboard data as a human-readable ASCII text block.
+ */
+function formatDashboardText(data) {
+    const lines = [];
+    const divider = '─'.repeat(50);
+    lines.push(divider);
+    lines.push(`  Resume Dashboard: ${data.runId}`);
+    lines.push(divider);
+    lines.push(`  Status:        ${data.status.toUpperCase()}`);
+    lines.push(`  Duration:      ${formatDurationMs(data.totalDuration)}`);
+    lines.push(`  Last activity: ${data.lastActivity}`);
+    lines.push('');
+    lines.push(`  Completed (${data.completedSteps.length}):`);
+    if (data.completedSteps.length === 0) {
+        lines.push('    (none)');
+    }
+    else {
+        for (const s of data.completedSteps) {
+            lines.push(`    [done] ${s.title}`);
+        }
+    }
+    lines.push(`  Pending (${data.pendingSteps.length}):`);
+    if (data.pendingSteps.length === 0) {
+        lines.push('    (none)');
+    }
+    else {
+        for (const s of data.pendingSteps) {
+            lines.push(`    [ .. ] ${s.title}`);
+        }
+    }
+    lines.push(`  Failed (${data.failedSteps.length}):`);
+    if (data.failedSteps.length === 0) {
+        lines.push('    (none)');
+    }
+    else {
+        for (const s of data.failedSteps) {
+            lines.push(`    [FAIL] ${s.title}`);
+        }
+    }
+    lines.push(divider);
+    return lines.join('\n');
+}

package/dist/observability/runStatus.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Run status and inspection APIs (GAP-OBS-001, GAP-UX-005, GAP-UX-006).
+ *
+ * - getRunHealthSnapshot: wraps computeRunHealthFromEvents with journal loading
+ * - getOrchestrationStatus: structured status view combining metadata, health, effects
+ * - getPendingWorkItems: detailed inspection of pending effects
+ */
+import type { RunHealthSnapshot } from "./types";
+/**
+ * Compute a health snapshot for a run by loading its journal.
+ */
+export declare function getRunHealthSnapshot(runDir: string): Promise<RunHealthSnapshot>;
+export type OrchestrationPhase = "created" | "running" | "waiting" | "completed" | "failed";
+export interface OrchestrationStatus {
+    runId: string;
+    processId: string;
+    phase: OrchestrationPhase;
+    iterationCount: number;
+    totalEffects: number;
+    pendingEffects: number;
+    resolvedEffects: number;
+    failedEffects: number;
+    health: RunHealthSnapshot;
+    createdAt: string;
+    lastActivityAt: string | null;
+}
+/**
+ * Get structured orchestration status for a run.
+ */
+export declare function getOrchestrationStatus(runDir: string): Promise<OrchestrationStatus>;
+export interface PendingWorkItem {
+    effectId: string;
+    taskId?: string;
+    kind?: string;
+    title?: string;
+    requestedAt: string;
+    ageMs: number;
+    labels?: string[];
+}
+/**
+ * List pending (unresolved) effects with rich detail.
+ */
+export declare function getPendingWorkItems(runDir: string): Promise<PendingWorkItem[]>;
+//# sourceMappingURL=runStatus.d.ts.map

package/dist/observability/runStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runStatus.d.ts","sourceRoot":"","sources":["../../src/observability/runStatus.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAMjD;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,iBAAiB,CAAC,CAG5B;AAMD,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,SAAS,GACT,SAAS,GACT,WAAW,GACX,QAAQ,CAAC;AAEb,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,mBAAmB,CAAC,CAqC9B;AAMD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,EAAE,CAAC,CA4E5B"}

package/dist/observability/runStatus.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Run status and inspection APIs (GAP-OBS-001, GAP-UX-005, GAP-UX-006).
+ *
+ * - getRunHealthSnapshot: wraps computeRunHealthFromEvents with journal loading
+ * - getOrchestrationStatus: structured status view combining metadata, health, effects
+ * - getPendingWorkItems: detailed inspection of pending effects
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRunHealthSnapshot = getRunHealthSnapshot;
+exports.getOrchestrationStatus = getOrchestrationStatus;
+exports.getPendingWorkItems = getPendingWorkItems;
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const babysitter_sdk_1 = require("@a5c-ai/babysitter-sdk");
+const health_1 = require("./health");
+// ---------------------------------------------------------------------------
+// GAP-OBS-001: Run Health Snapshot
+// ---------------------------------------------------------------------------
+/**
+ * Compute a health snapshot for a run by loading its journal.
+ */
+async function getRunHealthSnapshot(runDir) {
+    const events = await (0, babysitter_sdk_1.loadJournal)(runDir);
+    return (0, health_1.computeRunHealthFromEvents)(events);
+}
+/**
+ * Get structured orchestration status for a run.
+ */
+async function getOrchestrationStatus(runDir) {
+    const [metadata, events] = await Promise.all([
+        (0, babysitter_sdk_1.readRunMetadata)(runDir),
+        (0, babysitter_sdk_1.loadJournal)(runDir),
+    ]);
+    const health = (0, health_1.computeRunHealthFromEvents)(events);
+    // Determine phase from events
+    let phase = "created";
+    const hasCompleted = events.some((e) => e.type === "RUN_COMPLETED");
+    const hasFailed = events.some((e) => e.type === "RUN_FAILED");
+    const hasPending = health.metrics.pendingCount > 0;
+    if (hasFailed) {
+        phase = "failed";
+    }
+    else if (hasCompleted) {
+        phase = "completed";
+    }
+    else if (hasPending) {
+        phase = "waiting";
+    }
+    else if (events.length > 1) {
+        phase = "running";
+    }
+    return {
+        runId: metadata.runId,
+        processId: metadata.processId,
+        phase,
+        iterationCount: health.metrics.iterationCount,
+        totalEffects: health.metrics.totalEffects,
+        pendingEffects: health.metrics.pendingCount,
+        resolvedEffects: health.metrics.resolvedEffects,
+        failedEffects: health.metrics.failedEffects,
+        health,
+        createdAt: metadata.createdAt,
+        lastActivityAt: health.metrics.lastActivityAt,
+    };
+}
+/**
+ * List pending (unresolved) effects with rich detail.
+ */
+async function getPendingWorkItems(runDir) {
+    const events = await (0, babysitter_sdk_1.loadJournal)(runDir);
+    const now = Date.now();
+    // Track requested and resolved effect IDs
+    const requested = new Map();
+    const resolved = new Set();
+    for (const event of events) {
+        if (event.type === "EFFECT_REQUESTED") {
+            const effectId = typeof event.data.effectId === "string"
+                ? event.data.effectId
+                : undefined;
+            if (effectId) {
+                requested.set(effectId, {
+                    effectId,
+                    requestedAt: event.recordedAt,
+                    data: event.data,
+                });
+            }
+        }
+        if (event.type === "EFFECT_RESOLVED") {
+            const effectId = typeof event.data.effectId === "string"
+                ? event.data.effectId
+                : undefined;
+            if (effectId) {
+                resolved.add(effectId);
+            }
+        }
+    }
+    // Build pending items
+    const items = [];
+    for (const [effectId, req] of requested) {
+        if (resolved.has(effectId))
+            continue;
+        const reqTs = new Date(req.requestedAt).getTime();
+        // Try to read task definition for richer details
+        let title;
+        let kind;
+        let taskId;
+        let labels;
+        try {
+            const taskPath = path.join(runDir, "tasks", effectId, "task.json");
+            const raw = await node_fs_1.promises.readFile(taskPath, "utf-8");
+            const taskDef = JSON.parse(raw);
+            title = typeof taskDef.title === "string" ? taskDef.title : undefined;
+            kind = typeof taskDef.kind === "string" ? taskDef.kind : undefined;
+            taskId = typeof taskDef.taskId === "string" ? taskDef.taskId : undefined;
+            labels = Array.isArray(taskDef.labels) ? taskDef.labels : undefined;
+        }
+        catch {
+            // Task def may not exist for all effect types
+            kind = typeof req.data.kind === "string" ? req.data.kind : undefined;
+            taskId = typeof req.data.taskId === "string" ? req.data.taskId : undefined;
+        }
+        items.push({
+            effectId,
+            taskId,
+            kind,
+            title,
+            requestedAt: req.requestedAt,
+            ageMs: now - reqTs,
+            labels,
+        });
+    }
+    // Sort by age descending (oldest first)
+    items.sort((a, b) => b.ageMs - a.ageMs);
+    return items;
+}

package/dist/observability/subagentHealth.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Subagent Health Monitoring (GAP-SUBOBS-004).
+ *
+ * Monitors the liveness of delegated subagents via heartbeat tracking.
+ * Detects stale agents that have stopped reporting and surfaces health
+ * status for orchestration decision-making.
+ */
+export type SubagentHealthStatus = "healthy" | "degraded" | "stale" | "unknown";
+export interface SubagentHealthRecord {
+    /** Subagent identifier. */
+    id: string;
+    /** Current health status. */
+    status: SubagentHealthStatus;
+    /** Timestamp of the last heartbeat (ISO 8601). */
+    lastHeartbeatAt: string;
+    /** When the agent was first registered (ISO 8601). */
+    registeredAt: string;
+    /** Number of heartbeats received. */
+    heartbeatCount: number;
+}
+export interface SubagentHealthMonitorOptions {
+    /**
+     * Duration in milliseconds after which a subagent with no heartbeat
+     * is considered stale. Default: 60_000 (1 minute).
+     */
+    staleThresholdMs?: number;
+}
+/**
+ * Monitors subagent health via heartbeat registration and staleness checks.
+ */
+export declare class SubagentHealthMonitor {
+    private readonly records;
+    private readonly staleThresholdMs;
+    constructor(options?: SubagentHealthMonitorOptions);
+    /**
+     * Register a new subagent for health monitoring.
+     */
+    register(id: string): SubagentHealthRecord;
+    /**
+     * Record a heartbeat from a subagent.
+     * Marks the agent as healthy if it was previously unknown or degraded.
+     */
+    heartbeat(id: string): SubagentHealthRecord | undefined;
+    /**
+     * Check the health of a specific subagent at a given point in time.
+     * Updates the status based on elapsed time since last heartbeat.
+     */
+    checkHealth(id: string, now?: number): SubagentHealthRecord | undefined;
+    /**
+     * Get all subagents whose last heartbeat exceeds the stale threshold.
+     */
+    getStaleAgents(now?: number): SubagentHealthRecord[];
+    /**
+     * Get a specific record by id.
+     */
+    get(id: string): SubagentHealthRecord | undefined;
+    /**
+     * Get all registered records.
+     */
+    getAll(): SubagentHealthRecord[];
+    /**
+     * Unregister a subagent.
+     */
+    unregister(id: string): boolean;
+}
+//# sourceMappingURL=subagentHealth.d.ts.map

package/dist/observability/subagentHealth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagentHealth.d.ts","sourceRoot":"","sources":["../../src/observability/subagentHealth.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;AAEhF,MAAM,WAAW,oBAAoB;IACnC,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,6BAA6B;IAC7B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,kDAAkD;IAClD,eAAe,EAAE,MAAM,CAAC;IACxB,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,cAAc,EAAE,MAAM,CAAC;CACxB;AAMD,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAID;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2C;IACnE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,OAAO,CAAC,EAAE,4BAA4B;IAIlD;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB;IAa1C;;;OAGG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAUvD;;;OAGG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAoBvE;;OAEG;IACH,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,oBAAoB,EAAE;IAepD;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAIjD;;OAEG;IACH,MAAM,IAAI,oBAAoB,EAAE;IAIhC;;OAEG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;CAGhC"}