@a5c-ai/agent-platform 5.0.1-staging.04ca6ab00d21

package/dist/observability/timeline.d.ts

@@ -0,0 +1,11 @@
+/**
+ * GAP-OBS-NEW-002: Phase Timeline Visualization.
+ *
+ * Synthesizes phase timeline data from journal events. Identifies planning,
+ * execution, verification, and completion phases with duration metrics.
+ */
+import { type JournalEvent } from "@a5c-ai/babysitter-sdk";
+import type { PhaseTimeline } from "./types";
+export declare function buildPhaseTimelineFromEvents(events: JournalEvent[]): PhaseTimeline;
+export declare function buildPhaseTimeline(runDir: string): Promise<PhaseTimeline>;
+//# sourceMappingURL=timeline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../src/observability/timeline.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,KAAK,EACV,aAAa,EAKd,MAAM,SAAS,CAAC;AA2BjB,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,aAAa,CA6HlF;AAoCD,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAG/E"}

package/dist/observability/timeline.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * GAP-OBS-NEW-002: Phase Timeline Visualization.
+ *
+ * Synthesizes phase timeline data from journal events. Identifies planning,
+ * execution, verification, and completion phases with duration metrics.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPhaseTimelineFromEvents = buildPhaseTimelineFromEvents;
+exports.buildPhaseTimeline = buildPhaseTimeline;
+const babysitter_sdk_1 = require("@a5c-ai/babysitter-sdk");
+const VERIFICATION_TASK_IDS = new Set([
+    "typecheck",
+    "lint",
+    "run-tests",
+    "adversarial-review",
+]);
+function ms(a, b) {
+    return new Date(b).getTime() - new Date(a).getTime();
+}
+function makePhase(name, startedAt, endedAt) {
+    return {
+        name,
+        startedAt,
+        endedAt,
+        durationMs: endedAt ? ms(startedAt, endedAt) : null,
+    };
+}
+function isVerificationEvent(event) {
+    const taskId = event.data.taskId;
+    return taskId != null && VERIFICATION_TASK_IDS.has(taskId);
+}
+function buildPhaseTimelineFromEvents(events) {
+    if (events.length === 0) {
+        return {
+            phases: [],
+            milestones: [],
+            iterations: [],
+            currentPhase: "planning",
+            totalDurationMs: null,
+        };
+    }
+    const phases = [];
+    const milestones = [];
+    let currentPhase = "planning";
+    const firstEvent = events[0];
+    const lastEvent = events[events.length - 1];
+    // Find key transition points
+    const firstEffectReq = events.find((e) => e.type === "EFFECT_REQUESTED");
+    const runCompleted = events.find((e) => e.type === "RUN_COMPLETED");
+    const runFailed = events.find((e) => e.type === "RUN_FAILED");
+    // Find first verification event (typecheck/lint/test/review)
+    const firstVerificationReq = events.find((e) => e.type === "EFFECT_REQUESTED" && isVerificationEvent(e));
+    const lastVerificationResolved = [...events]
+        .reverse()
+        .find((e) => e.type === "EFFECT_RESOLVED" && isVerificationEvent(e));
+    // Phase 1: Planning — from RUN_CREATED to first EFFECT_REQUESTED
+    if (firstEvent.type === "RUN_CREATED") {
+        const planEnd = firstEffectReq?.recordedAt ?? null;
+        phases.push(makePhase("planning", firstEvent.recordedAt, planEnd));
+        if (planEnd) {
+            currentPhase = "execution";
+        }
+    }
+    // Phase 2: Execution — from first EFFECT_REQUESTED to verification start (or last resolved)
+    if (firstEffectReq) {
+        // Find the last non-verification EFFECT_RESOLVED as fallback execution end
+        const lastNonVerifResolved = [...events]
+            .reverse()
+            .find((e) => e.type === "EFFECT_RESOLVED" && !isVerificationEvent(e));
+        const execEnd = firstVerificationReq?.recordedAt
+            ?? runCompleted?.recordedAt
+            ?? runFailed?.recordedAt
+            ?? lastNonVerifResolved?.recordedAt
+            ?? null;
+        phases.push(makePhase("execution", firstEffectReq.recordedAt, execEnd));
+        currentPhase = execEnd ? (firstVerificationReq ? "verification" : "execution") : "execution";
+    }
+    // Phase 3: Verification — quality gates
+    if (firstVerificationReq) {
+        const verEnd = lastVerificationResolved?.recordedAt
+            ?? runCompleted?.recordedAt
+            ?? runFailed?.recordedAt
+            ?? null;
+        phases.push(makePhase("verification", firstVerificationReq.recordedAt, verEnd));
+        currentPhase = verEnd ? "completion" : "verification";
+    }
+    // Phase 4: Completion
+    if (runCompleted) {
+        phases.push(makePhase("completion", runCompleted.recordedAt, runCompleted.recordedAt));
+        currentPhase = "completed";
+    }
+    else if (runFailed) {
+        phases.push(makePhase("completion", runFailed.recordedAt, runFailed.recordedAt));
+        currentPhase = "failed";
+    }
+    // Extract milestones
+    for (const event of events) {
+        if (event.type === "EFFECT_RESOLVED" && event.data.kind === "breakpoint") {
+            milestones.push({
+                type: "breakpoint",
+                label: event.data.title ?? `Breakpoint ${event.data.effectId}`,
+                occurredAt: event.recordedAt,
+                data: event.data,
+            });
+        }
+        if (event.type === "EFFECT_RESOLVED" &&
+            (event.data.taskId === "adversarial-review")) {
+            milestones.push({
+                type: "quality-gate",
+                label: `Quality review: ${event.data.taskId}`,
+                occurredAt: event.recordedAt,
+                data: event.data,
+            });
+        }
+        if (event.type === "RUN_COMPLETED") {
+            milestones.push({
+                type: "run-completed",
+                label: "Run completed",
+                occurredAt: event.recordedAt,
+            });
+        }
+        if (event.type === "RUN_FAILED") {
+            milestones.push({
+                type: "run-failed",
+                label: "Run failed",
+                occurredAt: event.recordedAt,
+                data: event.data,
+            });
+        }
+    }
+    // Build iteration breakdowns
+    const iterations = buildIterations(events);
+    const totalDurationMs = events.length >= 2 ? ms(firstEvent.recordedAt, lastEvent.recordedAt) : null;
+    return {
+        phases,
+        milestones,
+        iterations,
+        currentPhase,
+        totalDurationMs,
+    };
+}
+function buildIterations(events) {
+    const iterationMap = new Map();
+    for (const event of events) {
+        const iter = event.data.iteration;
+        if (iter != null) {
+            let group = iterationMap.get(iter);
+            if (!group) {
+                group = [];
+                iterationMap.set(iter, group);
+            }
+            group.push(event);
+        }
+    }
+    const iterations = [];
+    for (const [iteration, iterEvents] of iterationMap) {
+        if (iterEvents.length === 0)
+            continue;
+        const first = iterEvents[0];
+        const last = iterEvents[iterEvents.length - 1];
+        const endedAt = last.type === "EFFECT_RESOLVED" ? last.recordedAt : null;
+        iterations.push({
+            iteration,
+            phases: [], // Per-iteration phase breakdown could be added later
+            startedAt: first.recordedAt,
+            endedAt,
+            durationMs: endedAt ? ms(first.recordedAt, endedAt) : null,
+        });
+    }
+    return iterations.sort((a, b) => a.iteration - b.iteration);
+}
+async function buildPhaseTimeline(runDir) {
+    const events = await (0, babysitter_sdk_1.loadJournal)(runDir);
+    return buildPhaseTimelineFromEvents(events);
+}

package/dist/observability/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Observability types.
+ *
+ * GAP-OBS-NEW-002: Phase Timeline types.
+ * GAP-STATE-008: Run Health Model types.
+ */
+export type RunHealthStatus = "healthy" | "degraded" | "stuck" | "failed";
+export interface RunHealthMetrics {
+    errorRate: number;
+    avgEffectLatencyMs: number;
+    pendingCount: number;
+    oldestPendingAgeMs: number;
+    iterationCount: number;
+    lastActivityAt: string | null;
+    totalEffects: number;
+    resolvedEffects: number;
+    failedEffects: number;
+}
+export interface RunHealthSnapshot {
+    status: RunHealthStatus;
+    metrics: RunHealthMetrics;
+    issues: string[];
+    computedAt: string;
+}
+export interface HealthConfig {
+    /** Threshold for detecting stuck runs (default: 300000ms = 5min). */
+    stuckThresholdMs: number;
+    /** Error rate above which run is 'degraded' (default: 0.3). */
+    degradedErrorRate: number;
+    /** Error rate above which run is 'failed' (default: 0.7). */
+    failedErrorRate: number;
+    /** Max age for pending effects before generating issue (default: 600000ms = 10min). */
+    maxPendingAge: number;
+}
+export type PhaseName = "planning" | "execution" | "verification" | "completion";
+export interface PhaseEntry {
+    name: PhaseName;
+    startedAt: string;
+    endedAt: string | null;
+    durationMs: number | null;
+}
+export interface Milestone {
+    type: "breakpoint" | "quality-gate" | "run-completed" | "run-failed";
+    label: string;
+    occurredAt: string;
+    data?: Record<string, unknown>;
+}
+export interface IterationTimeline {
+    iteration: number;
+    phases: PhaseEntry[];
+    startedAt: string;
+    endedAt: string | null;
+    durationMs: number | null;
+}
+export interface PhaseTimeline {
+    phases: PhaseEntry[];
+    milestones: Milestone[];
+    iterations: IterationTimeline[];
+    currentPhase: PhaseName | "completed" | "failed";
+    totalDurationMs: number | null;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/observability/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,eAAe,EAAE,MAAM,CAAC;IACxB,uFAAuF;IACvF,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,cAAc,GAAG,YAAY,CAAC;AAEjF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,YAAY,GAAG,cAAc,GAAG,eAAe,GAAG,YAAY,CAAC;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,YAAY,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IACjD,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC"}

package/dist/observability/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Observability types.
+ *
+ * GAP-OBS-NEW-002: Phase Timeline types.
+ * GAP-STATE-008: Run Health Model types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/observability/webhooks.d.ts

@@ -0,0 +1,68 @@
+/**
+ * GAP-OBS-NEW-001: Dashboard Webhook and Alert System.
+ *
+ * Webhook registration, event filtering, and alert evaluation
+ * for run health changes. Pure functions for registry management
+ * and alert level computation.
+ */
+import type { RunHealthSnapshot } from "./types";
+export type AlertLevel = "info" | "warn" | "critical";
+export type WebhookEventType = "run.health_changed" | "run.completed" | "run.failed" | "run.stuck" | "effect.pending_timeout";
+export interface WebhookRegistration {
+    id: string;
+    url: string;
+    events: WebhookEventType[];
+    runId?: string;
+    alertLevels?: AlertLevel[];
+    secret?: string;
+    createdAt: string;
+    enabled: boolean;
+}
+export interface WebhookEvent {
+    id: string;
+    type: WebhookEventType;
+    runId: string;
+    alertLevel: AlertLevel;
+    payload: Record<string, unknown>;
+    occurredAt: string;
+}
+export interface WebhookDeliveryResult {
+    webhookId: string;
+    success: boolean;
+    statusCode?: number;
+    error?: string;
+    deliveredAt: string;
+}
+export interface WebhookRegistry {
+    schemaVersion: string;
+    registrations: WebhookRegistration[];
+}
+export type WebhookRegistrationInput = Omit<WebhookRegistration, "id" | "createdAt">;
+export declare const WEBHOOK_SCHEMA_VERSION = "2026.01.webhooks-v1";
+/**
+ * Register a new webhook in the registry.
+ * Mutates the registry and returns the created registration.
+ */
+export declare function registerWebhook(registry: WebhookRegistry, input: WebhookRegistrationInput): WebhookRegistration;
+/**
+ * Remove a webhook by id. Throws if not found.
+ */
+export declare function unregisterWebhook(registry: WebhookRegistry, id: string): void;
+/**
+ * List webhooks, optionally filtered by runId.
+ */
+export declare function listWebhooks(registry: WebhookRegistry, runId?: string): WebhookRegistration[];
+/**
+ * Build a webhook event from a health snapshot.
+ */
+export declare function buildWebhookEvent(type: WebhookEventType, runId: string, snapshot: RunHealthSnapshot): WebhookEvent;
+/**
+ * Evaluate whether a health transition warrants an alert.
+ * Returns the alert level, or null if no alert is needed.
+ */
+export declare function evaluateAlertLevel(prev: RunHealthSnapshot | null, next: RunHealthSnapshot): AlertLevel | null;
+/**
+ * Filter registrations for a given event type and optional alert level.
+ */
+export declare function filterRegistrations(registrations: WebhookRegistration[], eventType: WebhookEventType, alertLevel?: AlertLevel): WebhookRegistration[];
+//# sourceMappingURL=webhooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/observability/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAmB,MAAM,SAAS,CAAC;AAMlE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAEtD,MAAM,MAAM,gBAAgB,GACxB,oBAAoB,GACpB,eAAe,GACf,YAAY,GACZ,WAAW,GACX,wBAAwB,CAAC;AAE7B,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,mBAAmB,EAAE,CAAC;CACtC;AAED,MAAM,MAAM,wBAAwB,GAAG,IAAI,CAAC,mBAAmB,EAAE,IAAI,GAAG,WAAW,CAAC,CAAC;AAMrF,eAAO,MAAM,sBAAsB,wBAAwB,CAAC;AA0B5D;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,wBAAwB,GAC9B,mBAAmB,CAQrB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,eAAe,EACzB,EAAE,EAAE,MAAM,GACT,IAAI,CAMN;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,eAAe,EACzB,KAAK,CAAC,EAAE,MAAM,GACb,mBAAmB,EAAE,CAGvB;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,iBAAiB,GAC1B,YAAY,CAad;AAMD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,iBAAiB,GAAG,IAAI,EAC9B,IAAI,EAAE,iBAAiB,GACtB,UAAU,GAAG,IAAI,CAgBnB;AAMD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,mBAAmB,EAAE,EACpC,SAAS,EAAE,gBAAgB,EAC3B,UAAU,CAAC,EAAE,UAAU,GACtB,mBAAmB,EAAE,CASvB"}

package/dist/observability/webhooks.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * GAP-OBS-NEW-001: Dashboard Webhook and Alert System.
+ *
+ * Webhook registration, event filtering, and alert evaluation
+ * for run health changes. Pure functions for registry management
+ * and alert level computation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBHOOK_SCHEMA_VERSION = void 0;
+exports.registerWebhook = registerWebhook;
+exports.unregisterWebhook = unregisterWebhook;
+exports.listWebhooks = listWebhooks;
+exports.buildWebhookEvent = buildWebhookEvent;
+exports.evaluateAlertLevel = evaluateAlertLevel;
+exports.filterRegistrations = filterRegistrations;
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+exports.WEBHOOK_SCHEMA_VERSION = "2026.01.webhooks-v1";
+// ---------------------------------------------------------------------------
+// ID generation
+// ---------------------------------------------------------------------------
+function generateId() {
+    // Use crypto.randomUUID for test isolation (no shared mutable counter)
+    return `wh-${crypto.randomUUID()}`;
+}
+// ---------------------------------------------------------------------------
+// Alert level mapping
+// ---------------------------------------------------------------------------
+const STATUS_ALERT_MAP = {
+    healthy: "info",
+    degraded: "warn",
+    stuck: "critical",
+    failed: "critical",
+};
+// ---------------------------------------------------------------------------
+// Registry management (pure, operates on mutable registry)
+// ---------------------------------------------------------------------------
+/**
+ * Register a new webhook in the registry.
+ * Mutates the registry and returns the created registration.
+ */
+function registerWebhook(registry, input) {
+    const registration = {
+        ...input,
+        id: generateId(),
+        createdAt: new Date().toISOString(),
+    };
+    registry.registrations.push(registration);
+    return registration;
+}
+/**
+ * Remove a webhook by id. Throws if not found.
+ */
+function unregisterWebhook(registry, id) {
+    const index = registry.registrations.findIndex((r) => r.id === id);
+    if (index === -1) {
+        throw new Error(`Webhook not found: ${id}`);
+    }
+    registry.registrations.splice(index, 1);
+}
+/**
+ * List webhooks, optionally filtered by runId.
+ */
+function listWebhooks(registry, runId) {
+    if (!runId)
+        return [...registry.registrations];
+    return registry.registrations.filter((r) => r.runId === runId);
+}
+// ---------------------------------------------------------------------------
+// Event building
+// ---------------------------------------------------------------------------
+/**
+ * Build a webhook event from a health snapshot.
+ */
+function buildWebhookEvent(type, runId, snapshot) {
+    return {
+        id: generateId(),
+        type,
+        runId,
+        alertLevel: STATUS_ALERT_MAP[snapshot.status],
+        payload: {
+            status: snapshot.status,
+            metrics: snapshot.metrics,
+            issues: snapshot.issues,
+        },
+        occurredAt: new Date().toISOString(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Alert level evaluation (pure)
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate whether a health transition warrants an alert.
+ * Returns the alert level, or null if no alert is needed.
+ */
+function evaluateAlertLevel(prev, next) {
+    const prevStatus = prev?.status ?? "healthy";
+    const nextStatus = next.status;
+    if (prevStatus === nextStatus)
+        return null;
+    // Recovery: anything → healthy
+    if (nextStatus === "healthy")
+        return "info";
+    // Degradation
+    if (nextStatus === "degraded")
+        return "warn";
+    // Critical states
+    if (nextStatus === "stuck" || nextStatus === "failed")
+        return "critical";
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Registration filtering
+// ---------------------------------------------------------------------------
+/**
+ * Filter registrations for a given event type and optional alert level.
+ */
+function filterRegistrations(registrations, eventType, alertLevel) {
+    return registrations.filter((r) => {
+        if (!r.enabled)
+            return false;
+        if (!r.events.includes(eventType))
+            return false;
+        if (alertLevel && r.alertLevels && r.alertLevels.length > 0) {
+            if (!r.alertLevels.includes(alertLevel))
+                return false;
+        }
+        return true;
+    });
+}

package/dist/plugins/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Plugin sandboxing module for L6 Agent-Platform.
+ *
+ * Provides permission-gated plugin loading, runtime sandbox enforcement,
+ * and semver compatibility checking.
+ */
+export type { PluginPermission, PluginManifest, PluginStatus, PluginInstance, PluginSandboxConfig, } from './types';
+export { PluginSandbox } from './sandbox';
+export { PluginLoader } from './loader';
+export { PluginVersionChecker, type VersionCheckResult } from './version-check';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,cAAc,EACd,mBAAmB,GACpB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,OAAO,EAAE,oBAAoB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/plugins/index.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Plugin sandboxing module for L6 Agent-Platform.
+ *
+ * Provides permission-gated plugin loading, runtime sandbox enforcement,
+ * and semver compatibility checking.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginVersionChecker = exports.PluginLoader = exports.PluginSandbox = void 0;
+// Sandbox
+var sandbox_1 = require("./sandbox");
+Object.defineProperty(exports, "PluginSandbox", { enumerable: true, get: function () { return sandbox_1.PluginSandbox; } });
+// Loader
+var loader_1 = require("./loader");
+Object.defineProperty(exports, "PluginLoader", { enumerable: true, get: function () { return loader_1.PluginLoader; } });
+// Version checker
+var version_check_1 = require("./version-check");
+Object.defineProperty(exports, "PluginVersionChecker", { enumerable: true, get: function () { return version_check_1.PluginVersionChecker; } });

package/dist/plugins/loader.d.ts

@@ -0,0 +1,37 @@
+/**
+ * PluginLoader — lifecycle manager for plugin instances.
+ *
+ * Tracks loaded plugins, validates manifests on load, and manages
+ * status transitions (loading -> loaded | error, unloading, reloading).
+ */
+import type { PluginManifest, PluginInstance } from './types';
+export declare class PluginLoader {
+    private plugins;
+    /**
+     * Load a plugin from its manifest.
+     *
+     * Validates required fields and permissions before transitioning the
+     * instance to `loaded`. If validation fails the instance is stored with
+     * status `error` and the error message is attached.
+     */
+    load(manifest: PluginManifest): PluginInstance;
+    /**
+     * Unload a plugin by id.
+     *
+     * Sets status to `unloaded`. Returns `true` if the plugin existed,
+     * `false` otherwise.
+     */
+    unload(pluginId: string): boolean;
+    /**
+     * Reload a plugin by re-loading from the existing manifest.
+     * Returns the new instance, or `undefined` if the plugin was not found.
+     */
+    reload(pluginId: string): PluginInstance | undefined;
+    /** Return all tracked plugin instances. */
+    list(): PluginInstance[];
+    /** Get a single plugin instance by id. */
+    get(pluginId: string): PluginInstance | undefined;
+    /** Check whether a plugin is currently loaded (status === 'loaded'). */
+    isLoaded(pluginId: string): boolean;
+}
+//# sourceMappingURL=loader.d.ts.map

package/dist/plugins/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/plugins/loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAoB,MAAM,SAAS,CAAC;AAahF,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAqC;IAMpD;;;;;;OAMG;IACH,IAAI,CAAC,QAAQ,EAAE,cAAc,GAAG,cAAc;IAqC9C;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAUjC;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAYpD,2CAA2C;IAC3C,IAAI,IAAI,cAAc,EAAE;IAIxB,0CAA0C;IAC1C,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAIjD,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;CAGpC"}

package/dist/plugins/loader.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * PluginLoader — lifecycle manager for plugin instances.
+ *
+ * Tracks loaded plugins, validates manifests on load, and manages
+ * status transitions (loading -> loaded | error, unloading, reloading).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginLoader = void 0;
+/** Set of all valid permission strings used for manifest validation. */
+const VALID_PERMISSIONS = new Set([
+    'fs:read',
+    'fs:write',
+    'net:outbound',
+    'process:spawn',
+    'env:read',
+    'mcp:connect',
+    'shell:execute',
+]);
+class PluginLoader {
+    plugins = new Map();
+    // ---------------------------------------------------------------------------
+    // Load / Unload / Reload
+    // ---------------------------------------------------------------------------
+    /**
+     * Load a plugin from its manifest.
+     *
+     * Validates required fields and permissions before transitioning the
+     * instance to `loaded`. If validation fails the instance is stored with
+     * status `error` and the error message is attached.
+     */
+    load(manifest) {
+        // Validate required fields
+        const issues = [];
+        if (!manifest.id)
+            issues.push('missing id');
+        if (!manifest.name)
+            issues.push('missing name');
+        if (!manifest.version)
+            issues.push('missing version');
+        if (!manifest.entrypoint)
+            issues.push('missing entrypoint');
+        if (!Array.isArray(manifest.permissions)) {
+            issues.push('permissions must be an array');
+        }
+        else {
+            for (const perm of manifest.permissions) {
+                if (!VALID_PERMISSIONS.has(perm)) {
+                    issues.push(`unknown permission: ${perm}`);
+                }
+            }
+        }
+        if (issues.length > 0) {
+            const instance = {
+                manifest,
+                status: 'error',
+                error: `Manifest validation failed: ${issues.join('; ')}`,
+            };
+            this.plugins.set(manifest.id, instance);
+            return instance;
+        }
+        const instance = {
+            manifest,
+            status: 'loaded',
+            loadedAt: Date.now(),
+        };
+        this.plugins.set(manifest.id, instance);
+        return instance;
+    }
+    /**
+     * Unload a plugin by id.
+     *
+     * Sets status to `unloaded`. Returns `true` if the plugin existed,
+     * `false` otherwise.
+     */
+    unload(pluginId) {
+        const instance = this.plugins.get(pluginId);
+        if (!instance)
+            return false;
+        instance.status = 'unloaded';
+        instance.loadedAt = undefined;
+        instance.error = undefined;
+        return true;
+    }
+    /**
+     * Reload a plugin by re-loading from the existing manifest.
+     * Returns the new instance, or `undefined` if the plugin was not found.
+     */
+    reload(pluginId) {
+        const existing = this.plugins.get(pluginId);
+        if (!existing)
+            return undefined;
+        this.unload(pluginId);
+        return this.load(existing.manifest);
+    }
+    // ---------------------------------------------------------------------------
+    // Queries
+    // ---------------------------------------------------------------------------
+    /** Return all tracked plugin instances. */
+    list() {
+        return [...this.plugins.values()];
+    }
+    /** Get a single plugin instance by id. */
+    get(pluginId) {
+        return this.plugins.get(pluginId);
+    }
+    /** Check whether a plugin is currently loaded (status === 'loaded'). */
+    isLoaded(pluginId) {
+        return this.plugins.get(pluginId)?.status === 'loaded';
+    }
+}
+exports.PluginLoader = PluginLoader;