@beingmartinbmc/ojas 0.2.0

package/dist/pulse/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Ojas Pulse — AI Health Telemetry System
+ *
+ * Tracks cognitive vital signs, degradation signals, and health events.
+ */
+import { HealthEvent, HealthRecommendation, LatencyStats, StuckAgentReport, TelemetryHealth, TelemetryPolicy } from '../types';
+import type { PulseStateSnapshot } from '../persistence/types';
+/** Callback invoked for every emitted `HealthEvent`. Subscriber errors are swallowed. */
+export type HealthEventSubscriber = (event: HealthEvent) => void;
+/** Returned by `Pulse.subscribe()` — call to detach. */
+export type Unsubscribe = () => void;
+/**
+ * Standard context-budget milestone thresholds. Emits a structured
+ * "you've used 50% / 75% / 90% / 95% of your context window" event
+ * the first time each milestone is crossed. Latched per-agent so an
+ * agent that just crossed 75% doesn't keep getting paged about it.
+ */
+export declare const CONTEXT_BUDGET_MILESTONES: readonly [0.5, 0.75, 0.9, 0.95];
+export type ContextBudgetMilestone = (typeof CONTEXT_BUDGET_MILESTONES)[number];
+export declare class Pulse {
+    private policy;
+    private events;
+    /**
+     * Latch tracking which context-budget milestones have already been
+     * emitted for each agent. Resets when the agent's utilisation falls
+     * back below the milestone (so the next crossing emits again).
+     * Key: agentId. Value: set of milestones currently latched.
+     */
+    private budgetMilestonesEmitted;
+    /**
+     * Latch tracking which memory IDs have already produced a
+     * `memory_cold` event. Cleared per-memory by `clearColdMemoryLatch`.
+     */
+    private coldMemoryEmitted;
+    /**
+     * Trailing latency samples per `(agentId, taskClass)` key. The key
+     * format is `${agentId}::${taskClass}`. Each entry is an array of
+     * millisecond durations capped at `policy.latencyWindowSize`.
+     */
+    private latencyWindows;
+    /**
+     * Latch per `(agentId, taskClass)` for `latency_breach` events.
+     * Cleared when the windowed p95 falls back below the policy budget
+     * so a sustained breach paged once, not on every sample.
+     */
+    private latencyBreachLatched;
+    /** Last `heartbeat()` ISO timestamp per agentId. */
+    private lastHeartbeatAt;
+    /**
+     * Per-agent latch for `agent_stuck` event. Set when
+     * `detectStuckAgents()` flags the agent as stuck, cleared on the
+     * next heartbeat. Prevents continuous paging while the agent
+     * remains silent.
+     */
+    private stuckLatched;
+    /** Active push-subscribers. Errors thrown inside handlers are swallowed. */
+    private subscribers;
+    constructor(policy?: Partial<TelemetryPolicy>);
+    /**
+     * Record context-budget utilisation for `agentId` and emit a
+     * `context_budget_milestone` event for each newly crossed
+     * milestone (50/75/90/95 percent). Idempotent — re-recording the
+     * same utilisation never re-emits.
+     *
+     * Returns the list of milestone fractions that emitted on this call
+     * (empty when nothing crossed).
+     */
+    recordContextBudgetUtilisation(agentId: string, tokensUsed: number, tokensMax: number): ContextBudgetMilestone[];
+    /**
+     * Emit a `memory_cold` event for each item in `items` that hasn't
+     * already been notified. Each item is `{ id, temperature, abstraction }`,
+     * matching the shape produced by `Nidra.detectColdMemories()`. Returns
+     * the IDs that actually triggered an emission this call.
+     */
+    recordColdMemories(agentId: string, items: {
+        id: string;
+        temperature: number;
+        abstraction: string;
+    }[]): string[];
+    /** Clear the cold-memory latch for `id` (e.g. after the memory was re-warmed or compacted). */
+    clearColdMemoryLatch(id: string): void;
+    /**
+     * Reject malformed TelemetryPolicy fields. `maxRecentEvents` drives the
+     * trailing event window used by `emit` and `assess`; a non-positive or
+     * non-finite value would either silently disable retention or crash on
+     * `Array.slice(-NaN)`.
+     */
+    private validatePolicy;
+    emit(event: HealthEvent): void;
+    emitMany(events: HealthEvent[]): void;
+    assess(): TelemetryHealth;
+    recommend(): HealthRecommendation[];
+    getEvents(): readonly Readonly<HealthEvent>[];
+    exportState(): PulseStateSnapshot;
+    importState(snapshot: Partial<PulseStateSnapshot> | undefined): void;
+    getPolicy(): TelemetryPolicy;
+    updatePolicy(updates: Partial<TelemetryPolicy>): void;
+    /**
+     * Push-subscribe to every emitted `HealthEvent`. The returned function
+     * detaches the subscriber. Handler exceptions are swallowed so a
+     * buggy subscriber can never corrupt Pulse state. Useful for live
+     * dashboards, log streaming, and external alerting integrations.
+     */
+    subscribe(handler: HealthEventSubscriber): Unsubscribe;
+    /**
+     * Record a single observed task latency. Adds the sample to the
+     * trailing per-(agentId, taskClass) window, returns the resulting
+     * windowed stats, and \u2014 if `policy.latencyP95BreachMs` is configured
+     * and the new windowed p95 exceeds it \u2014 emits a one-shot
+     * `latency_breach` event. The breach latch clears when p95 drops
+     * back below the budget so a recovered system can re-page on a
+     * future breach.
+     *
+     * Rejects malformed input (non-finite or negative `durationMs`,
+     * empty strings) at the boundary so a buggy caller can't poison
+     * percentile math.
+     */
+    recordLatency(agentId: string, taskClass: string, durationMs: number): LatencyStats;
+    /**
+     * Windowed latency summary for one `(agentId, taskClass)`. Returns a
+     * zero-valued struct when no samples have been recorded yet.
+     */
+    getLatencyStats(agentId: string, taskClass: string): LatencyStats;
+    private computeLatencyStats;
+    /**
+     * Stamp `agentId` as alive *now*. Clears the per-agent stuck latch
+     * so a subsequent silence can re-fire a fresh `agent_stuck` event.
+     */
+    heartbeat(agentId: string): void;
+    /** Last heartbeat timestamp for `agentId`, or `undefined` if never seen. */
+    getLastHeartbeat(agentId: string): string | undefined;
+    /**
+     * Identify agents whose last `heartbeat()` is older than the
+     * configured `stuckAfterMs` budget. For each newly-stuck agent
+     * (latched per agentId), emits an `agent_stuck` event. The latch
+     * clears on the next heartbeat from that agent.
+     *
+     * `maxIdleMs` overrides the policy budget for this call. Agents
+     * that have never sent a heartbeat are not reported \u2014 they're not
+     * "stuck", they're "unknown".
+     */
+    detectStuckAgents(maxIdleMs?: number): StuckAgentReport[];
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pulse/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAEL,WAAW,EACX,oBAAoB,EAEpB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,eAAe,EAChB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,yFAAyF;AACzF,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;AACjE,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAcrC;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,iCAAkC,CAAC;AAEzE,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhF,qBAAa,KAAK;IAChB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,MAAM,CAAqB;IACnC;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB,CAAkD;IACjF;;;OAGG;IACH,OAAO,CAAC,iBAAiB,CAAqB;IAC9C;;;;OAIG;IACH,OAAO,CAAC,cAAc,CAA+B;IACrD;;;;OAIG;IACH,OAAO,CAAC,oBAAoB,CAAqB;IACjD,oDAAoD;IACpD,OAAO,CAAC,eAAe,CAA6B;IACpD;;;;;OAKG;IACH,OAAO,CAAC,YAAY,CAAqB;IACzC,4EAA4E;IAC5E,OAAO,CAAC,WAAW,CAA+B;gBAEtC,MAAM,GAAE,OAAO,CAAC,eAAe,CAAM;IAIjD;;;;;;;;OAQG;IACH,8BAA8B,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,sBAAsB,EAAE;IAwC3B;;;;;OAKG;IACH,kBAAkB,CAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,GAChE,MAAM,EAAE;IAuBX,+FAA+F;IAC/F,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAItC;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAiCtB,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAkB9B,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI;IAIrC,MAAM,IAAI,eAAe;IAgBzB,SAAS,IAAI,oBAAoB,EAAE;IA6BnC,SAAS,IAAI,SAAS,QAAQ,CAAC,WAAW,CAAC,EAAE;IAI7C,WAAW,IAAI,kBAAkB;IAYjC,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,SAAS,GAAG,IAAI;IAapE,SAAS,IAAI,eAAe;IAI5B,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI;IASrD;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,qBAAqB,GAAG,WAAW;IAatD;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY;IAgDnF;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY;IAMjE,OAAO,CAAC,mBAAmB;IAuB3B;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQhC,4EAA4E;IAC5E,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIrD;;;;;;;;;OASG;IACH,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,gBAAgB,EAAE;CA8B1D"}

package/dist/pulse/index.js

@@ -0,0 +1,453 @@
+"use strict";
+/**
+ * Ojas Pulse — AI Health Telemetry System
+ *
+ * Tracks cognitive vital signs, degradation signals, and health events.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Pulse = exports.CONTEXT_BUDGET_MILESTONES = void 0;
+const types_1 = require("../types");
+function now() {
+    return new Date().toISOString();
+}
+function clamp(v, min = 0, max = 1) {
+    return Math.max(min, Math.min(max, v));
+}
+function healthScore(value, source) {
+    return { value: clamp(value), timestamp: now(), source };
+}
+/**
+ * Standard context-budget milestone thresholds. Emits a structured
+ * "you've used 50% / 75% / 90% / 95% of your context window" event
+ * the first time each milestone is crossed. Latched per-agent so an
+ * agent that just crossed 75% doesn't keep getting paged about it.
+ */
+exports.CONTEXT_BUDGET_MILESTONES = [0.5, 0.75, 0.9, 0.95];
+class Pulse {
+    policy;
+    events = [];
+    /**
+     * Latch tracking which context-budget milestones have already been
+     * emitted for each agent. Resets when the agent's utilisation falls
+     * back below the milestone (so the next crossing emits again).
+     * Key: agentId. Value: set of milestones currently latched.
+     */
+    budgetMilestonesEmitted = new Map();
+    /**
+     * Latch tracking which memory IDs have already produced a
+     * `memory_cold` event. Cleared per-memory by `clearColdMemoryLatch`.
+     */
+    coldMemoryEmitted = new Set();
+    /**
+     * Trailing latency samples per `(agentId, taskClass)` key. The key
+     * format is `${agentId}::${taskClass}`. Each entry is an array of
+     * millisecond durations capped at `policy.latencyWindowSize`.
+     */
+    latencyWindows = new Map();
+    /**
+     * Latch per `(agentId, taskClass)` for `latency_breach` events.
+     * Cleared when the windowed p95 falls back below the policy budget
+     * so a sustained breach paged once, not on every sample.
+     */
+    latencyBreachLatched = new Set();
+    /** Last `heartbeat()` ISO timestamp per agentId. */
+    lastHeartbeatAt = new Map();
+    /**
+     * Per-agent latch for `agent_stuck` event. Set when
+     * `detectStuckAgents()` flags the agent as stuck, cleared on the
+     * next heartbeat. Prevents continuous paging while the agent
+     * remains silent.
+     */
+    stuckLatched = new Set();
+    /** Active push-subscribers. Errors thrown inside handlers are swallowed. */
+    subscribers = [];
+    constructor(policy = {}) {
+        this.policy = this.validatePolicy({ ...types_1.DEFAULT_TELEMETRY_POLICY, ...policy });
+    }
+    /**
+     * Record context-budget utilisation for `agentId` and emit a
+     * `context_budget_milestone` event for each newly crossed
+     * milestone (50/75/90/95 percent). Idempotent — re-recording the
+     * same utilisation never re-emits.
+     *
+     * Returns the list of milestone fractions that emitted on this call
+     * (empty when nothing crossed).
+     */
+    recordContextBudgetUtilisation(agentId, tokensUsed, tokensMax) {
+        if (!Number.isFinite(tokensUsed) || !Number.isFinite(tokensMax) || tokensMax <= 0) {
+            return [];
+        }
+        const ratio = Math.max(0, tokensUsed / tokensMax);
+        const latched = this.budgetMilestonesEmitted.get(agentId) ?? new Set();
+        const newlyCrossed = [];
+        for (const m of exports.CONTEXT_BUDGET_MILESTONES) {
+            if (ratio >= m && !latched.has(m)) {
+                latched.add(m);
+                newlyCrossed.push(m);
+            }
+            else if (ratio < m && latched.has(m)) {
+                // Fell back below — un-latch so the next crossing can emit again.
+                latched.delete(m);
+            }
+        }
+        if (latched.size > 0)
+            this.budgetMilestonesEmitted.set(agentId, latched);
+        else
+            this.budgetMilestonesEmitted.delete(agentId);
+        for (const m of newlyCrossed) {
+            const severity = m >= 0.95 ? 'critical' : m >= 0.9 ? 'warning' : 'info';
+            this.emit({
+                id: `pulse-budget-${agentId}-${Math.round(m * 100)}-${Date.now()}`,
+                eventType: 'context_budget_milestone',
+                severity,
+                timestamp: now(),
+                agentId,
+                detectedBy: 'pulse',
+                details: {
+                    milestone: m,
+                    tokensUsed,
+                    tokensMax,
+                    utilisation: ratio,
+                },
+            });
+        }
+        return newlyCrossed;
+    }
+    /**
+     * Emit a `memory_cold` event for each item in `items` that hasn't
+     * already been notified. Each item is `{ id, temperature, abstraction }`,
+     * matching the shape produced by `Nidra.detectColdMemories()`. Returns
+     * the IDs that actually triggered an emission this call.
+     */
+    recordColdMemories(agentId, items) {
+        const emitted = [];
+        for (const c of items) {
+            if (this.coldMemoryEmitted.has(c.id))
+                continue;
+            this.coldMemoryEmitted.add(c.id);
+            emitted.push(c.id);
+            this.emit({
+                id: `pulse-cold-${c.id}-${Date.now()}`,
+                eventType: 'memory_cold',
+                severity: 'info',
+                timestamp: now(),
+                agentId,
+                detectedBy: 'pulse',
+                details: {
+                    memoryId: c.id,
+                    temperature: c.temperature,
+                    abstraction: c.abstraction,
+                },
+            });
+        }
+        return emitted;
+    }
+    /** Clear the cold-memory latch for `id` (e.g. after the memory was re-warmed or compacted). */
+    clearColdMemoryLatch(id) {
+        this.coldMemoryEmitted.delete(id);
+    }
+    /**
+     * Reject malformed TelemetryPolicy fields. `maxRecentEvents` drives the
+     * trailing event window used by `emit` and `assess`; a non-positive or
+     * non-finite value would either silently disable retention or crash on
+     * `Array.slice(-NaN)`.
+     */
+    validatePolicy(policy) {
+        if (!Number.isInteger(policy.maxRecentEvents) || policy.maxRecentEvents <= 0) {
+            throw new Error('Pulse: maxRecentEvents must be a positive integer');
+        }
+        if (typeof policy.degradationThreshold !== 'number' ||
+            !Number.isFinite(policy.degradationThreshold) ||
+            policy.degradationThreshold < 0 ||
+            policy.degradationThreshold > 1) {
+            throw new Error('Pulse: degradationThreshold must be a finite number in [0,1]');
+        }
+        if (policy.latencyWindowSize !== undefined &&
+            (!Number.isInteger(policy.latencyWindowSize) || policy.latencyWindowSize <= 0)) {
+            throw new Error('Pulse: latencyWindowSize must be a positive integer if set');
+        }
+        if (policy.latencyP95BreachMs !== undefined &&
+            (!Number.isFinite(policy.latencyP95BreachMs) || policy.latencyP95BreachMs <= 0)) {
+            throw new Error('Pulse: latencyP95BreachMs must be a positive finite number if set');
+        }
+        if (policy.stuckAfterMs !== undefined &&
+            (!Number.isFinite(policy.stuckAfterMs) || policy.stuckAfterMs <= 0)) {
+            throw new Error('Pulse: stuckAfterMs must be a positive finite number if set');
+        }
+        return policy;
+    }
+    emit(event) {
+        this.events.push(event);
+        if (this.events.length > this.policy.maxRecentEvents) {
+            this.events = this.events.slice(-this.policy.maxRecentEvents);
+        }
+        // Push to subscribers. Errors inside handlers are caught so a buggy
+        // subscriber can't corrupt Pulse state mid-emit.
+        if (this.subscribers.length > 0) {
+            for (const sub of this.subscribers) {
+                try {
+                    sub(event);
+                }
+                catch {
+                    // Intentional: subscriber errors must not break the emit path.
+                }
+            }
+        }
+    }
+    emitMany(events) {
+        for (const event of events)
+            this.emit(event);
+    }
+    assess() {
+        const recent = this.events.slice(-this.policy.maxRecentEvents);
+        const critical = recent.filter((event) => event.severity === 'critical').length;
+        const warning = recent.filter((event) => event.severity === 'warning').length;
+        const activeAlerts = critical + warning;
+        const degradationRisk = clamp((critical * 0.2) + (warning * 0.05));
+        return {
+            vitalSigns: healthScore(1 - degradationRisk, 'pulse.vitalSigns'),
+            degradationRisk: healthScore(1 - degradationRisk, 'pulse.degradationRisk'),
+            observabilityCoverage: healthScore(recent.length > 0 ? 1 : 0.4, 'pulse.coverage'),
+            eventsEmitted: recent.length,
+            activeAlerts,
+        };
+    }
+    recommend() {
+        const health = this.assess();
+        const recs = [];
+        if (health.activeAlerts > 0) {
+            recs.push({
+                module: 'pulse',
+                severity: health.degradationRisk.value < 0.5 ? 'critical' : 'warning',
+                message: `${health.activeAlerts} active health alerts detected.`,
+                action: 'Inspect recent health events and trigger recovery or repair if needed.',
+            });
+        }
+        if (health.observabilityCoverage.value < 0.5) {
+            recs.push({
+                module: 'pulse',
+                severity: 'warning',
+                message: 'Telemetry coverage is low; no recent health events are available.',
+                action: 'Connect Pulse to runtime traces and module events.',
+            });
+        }
+        if (recs.length === 0) {
+            recs.push({ module: 'pulse', severity: 'info', message: 'Health telemetry is stable.' });
+        }
+        return recs;
+    }
+    getEvents() {
+        return this.events.map((e) => ({ ...e, details: { ...e.details } }));
+    }
+    exportState() {
+        return {
+            events: [...this.getEvents()],
+            budgetMilestonesEmitted: Array.from(this.budgetMilestonesEmitted.entries()).map(([k, v]) => [k, Array.from(v)]),
+            coldMemoryEmitted: Array.from(this.coldMemoryEmitted),
+            latencyWindows: Array.from(this.latencyWindows.entries()).map(([k, v]) => [k, [...v]]),
+            latencyBreachLatched: Array.from(this.latencyBreachLatched),
+            lastHeartbeatAt: Array.from(this.lastHeartbeatAt.entries()),
+            stuckLatched: Array.from(this.stuckLatched),
+        };
+    }
+    importState(snapshot) {
+        if (!snapshot)
+            return;
+        this.events = (snapshot.events ?? []).map((e) => ({ ...e, details: { ...e.details } }));
+        this.budgetMilestonesEmitted = new Map((snapshot.budgetMilestonesEmitted ?? []).map(([k, v]) => [k, new Set(v)]));
+        this.coldMemoryEmitted = new Set(snapshot.coldMemoryEmitted ?? []);
+        this.latencyWindows = new Map((snapshot.latencyWindows ?? []).map(([k, v]) => [k, [...v]]));
+        this.latencyBreachLatched = new Set(snapshot.latencyBreachLatched ?? []);
+        this.lastHeartbeatAt = new Map(snapshot.lastHeartbeatAt ?? []);
+        this.stuckLatched = new Set(snapshot.stuckLatched ?? []);
+    }
+    getPolicy() {
+        return { ...this.policy };
+    }
+    updatePolicy(updates) {
+        this.policy = this.validatePolicy({ ...this.policy, ...updates });
+        if (this.events.length > this.policy.maxRecentEvents) {
+            this.events = this.events.slice(-this.policy.maxRecentEvents);
+        }
+    }
+    // ── Push subscription ────────────────────────────────────────────────────
+    /**
+     * Push-subscribe to every emitted `HealthEvent`. The returned function
+     * detaches the subscriber. Handler exceptions are swallowed so a
+     * buggy subscriber can never corrupt Pulse state. Useful for live
+     * dashboards, log streaming, and external alerting integrations.
+     */
+    subscribe(handler) {
+        if (typeof handler !== 'function') {
+            throw new Error('Pulse: subscribe requires a function handler');
+        }
+        this.subscribers.push(handler);
+        return () => {
+            const idx = this.subscribers.indexOf(handler);
+            if (idx !== -1)
+                this.subscribers.splice(idx, 1);
+        };
+    }
+    // ── Latency tracking ─────────────────────────────────────────────────────
+    /**
+     * Record a single observed task latency. Adds the sample to the
+     * trailing per-(agentId, taskClass) window, returns the resulting
+     * windowed stats, and \u2014 if `policy.latencyP95BreachMs` is configured
+     * and the new windowed p95 exceeds it \u2014 emits a one-shot
+     * `latency_breach` event. The breach latch clears when p95 drops
+     * back below the budget so a recovered system can re-page on a
+     * future breach.
+     *
+     * Rejects malformed input (non-finite or negative `durationMs`,
+     * empty strings) at the boundary so a buggy caller can't poison
+     * percentile math.
+     */
+    recordLatency(agentId, taskClass, durationMs) {
+        if (typeof agentId !== 'string' || agentId.length === 0) {
+            throw new Error('Pulse: recordLatency requires a non-empty agentId');
+        }
+        if (typeof taskClass !== 'string' || taskClass.length === 0) {
+            throw new Error('Pulse: recordLatency requires a non-empty taskClass');
+        }
+        if (typeof durationMs !== 'number' || !Number.isFinite(durationMs) || durationMs < 0) {
+            throw new Error('Pulse: recordLatency requires a non-negative finite durationMs');
+        }
+        const key = `${agentId}::${taskClass}`;
+        const cap = this.policy.latencyWindowSize ?? 100;
+        let window = this.latencyWindows.get(key);
+        if (!window) {
+            window = [];
+            this.latencyWindows.set(key, window);
+        }
+        window.push(durationMs);
+        if (window.length > cap) {
+            window.splice(0, window.length - cap);
+        }
+        const stats = this.computeLatencyStats(agentId, taskClass, window);
+        const budget = this.policy.latencyP95BreachMs;
+        if (budget !== undefined) {
+            if (stats.p95Ms > budget && !this.latencyBreachLatched.has(key)) {
+                this.latencyBreachLatched.add(key);
+                this.emit({
+                    id: `pulse-latency-${key}-${Date.now()}`,
+                    eventType: 'latency_breach',
+                    severity: 'warning',
+                    timestamp: now(),
+                    agentId,
+                    detectedBy: 'pulse',
+                    details: {
+                        taskClass,
+                        p95Ms: stats.p95Ms,
+                        budgetMs: budget,
+                        samples: stats.samples,
+                    },
+                });
+            }
+            else if (stats.p95Ms <= budget && this.latencyBreachLatched.has(key)) {
+                this.latencyBreachLatched.delete(key);
+            }
+        }
+        return stats;
+    }
+    /**
+     * Windowed latency summary for one `(agentId, taskClass)`. Returns a
+     * zero-valued struct when no samples have been recorded yet.
+     */
+    getLatencyStats(agentId, taskClass) {
+        const key = `${agentId}::${taskClass}`;
+        const window = this.latencyWindows.get(key);
+        return this.computeLatencyStats(agentId, taskClass, window ?? []);
+    }
+    computeLatencyStats(agentId, taskClass, samples) {
+        if (samples.length === 0) {
+            return { agentId, taskClass, samples: 0, meanMs: 0, p50Ms: 0, p95Ms: 0, maxMs: 0 };
+        }
+        const sorted = [...samples].sort((a, b) => a - b);
+        const sum = sorted.reduce((acc, v) => acc + v, 0);
+        return {
+            agentId,
+            taskClass,
+            samples: sorted.length,
+            meanMs: sum / sorted.length,
+            p50Ms: percentileSample(sorted, 0.5),
+            p95Ms: percentileSample(sorted, 0.95),
+            maxMs: sorted[sorted.length - 1],
+        };
+    }
+    // ── Heartbeat / stuck-agent detection ────────────────────────────────────
+    /**
+     * Stamp `agentId` as alive *now*. Clears the per-agent stuck latch
+     * so a subsequent silence can re-fire a fresh `agent_stuck` event.
+     */
+    heartbeat(agentId) {
+        if (typeof agentId !== 'string' || agentId.length === 0) {
+            throw new Error('Pulse: heartbeat requires a non-empty agentId');
+        }
+        this.lastHeartbeatAt.set(agentId, now());
+        this.stuckLatched.delete(agentId);
+    }
+    /** Last heartbeat timestamp for `agentId`, or `undefined` if never seen. */
+    getLastHeartbeat(agentId) {
+        return this.lastHeartbeatAt.get(agentId);
+    }
+    /**
+     * Identify agents whose last `heartbeat()` is older than the
+     * configured `stuckAfterMs` budget. For each newly-stuck agent
+     * (latched per agentId), emits an `agent_stuck` event. The latch
+     * clears on the next heartbeat from that agent.
+     *
+     * `maxIdleMs` overrides the policy budget for this call. Agents
+     * that have never sent a heartbeat are not reported \u2014 they're not
+     * "stuck", they're "unknown".
+     */
+    detectStuckAgents(maxIdleMs) {
+        const budget = maxIdleMs ?? this.policy.stuckAfterMs ?? 60_000;
+        const nowMs = Date.now();
+        const out = [];
+        for (const [agentId, ts] of this.lastHeartbeatAt) {
+            const idleMs = nowMs - Date.parse(ts);
+            // `>=`: at the moment the agent's idle reaches the configured
+            // budget it counts as stuck. A budget of 0 therefore means "any
+            // agent that has ever sent a heartbeat" — useful for tests.
+            if (idleMs < budget)
+                continue;
+            out.push({ agentId, lastHeartbeatAt: ts, idleMs });
+            if (!this.stuckLatched.has(agentId)) {
+                this.stuckLatched.add(agentId);
+                this.emit({
+                    id: `pulse-stuck-${agentId}-${nowMs}`,
+                    eventType: 'agent_stuck',
+                    severity: idleMs > budget * 4 ? 'critical' : 'warning',
+                    timestamp: now(),
+                    agentId,
+                    detectedBy: 'pulse',
+                    details: {
+                        lastHeartbeatAt: ts,
+                        idleMs,
+                        budgetMs: budget,
+                    },
+                });
+            }
+        }
+        return out;
+    }
+}
+exports.Pulse = Pulse;
+/**
+ * Linear-interpolated percentile over a sorted-ascending sample.
+ * Kept module-private (sibling helper of `Pulse.computeLatencyStats`)
+ * so the dependency footprint stays at zero.
+ */
+function percentileSample(sortedAsc, p) {
+    if (sortedAsc.length === 0)
+        return 0;
+    const q = Math.max(0, Math.min(1, p));
+    const idx = q * (sortedAsc.length - 1);
+    const lo = Math.floor(idx);
+    const hi = Math.ceil(idx);
+    if (lo === hi)
+        return sortedAsc[lo];
+    const w = idx - lo;
+    return sortedAsc[lo] * (1 - w) + sortedAsc[hi] * w;
+}
+//# sourceMappingURL=index.js.map

package/dist/pulse/index.js.map

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

package/dist/raksha/classifiers/http-classifier.d.ts

@@ -0,0 +1,26 @@
+/**
+ * HTTP-backed prompt injection classifier — reference implementation.
+ *
+ * Calls an external HTTP endpoint that accepts `{ text }` and returns
+ * `{ injectionProbability, label }`.  Works with any service that follows
+ * this contract (e.g. a Python FastAPI wrapping a HuggingFace classifier,
+ * the OpenAI moderation endpoint behind a thin adapter, Rebuff, etc.).
+ */
+import type { PromptInjectionClassifier, ClassifierResult } from '../../types';
+export interface HttpClassifierOptions {
+    /** Full URL of the classification endpoint. */
+    url: string;
+    /** Optional bearer token for authenticated endpoints. */
+    apiKey?: string;
+    /** Request timeout in milliseconds.  Default: 5000. */
+    timeoutMs?: number;
+    /** Custom headers merged into every request. */
+    headers?: Record<string, string>;
+}
+export declare class HttpPromptInjectionClassifier implements PromptInjectionClassifier {
+    readonly name: string;
+    private readonly opts;
+    constructor(options: HttpClassifierOptions);
+    classify(text: string, signal?: AbortSignal): Promise<ClassifierResult>;
+}
+//# sourceMappingURL=http-classifier.d.ts.map

package/dist/raksha/classifiers/http-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-classifier.d.ts","sourceRoot":"","sources":["../../../src/raksha/classifiers/http-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/E,MAAM,WAAW,qBAAqB;IACpC,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,qBAAa,6BAA8B,YAAW,yBAAyB;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkH;gBAE3H,OAAO,EAAE,qBAAqB;IAUpC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAyC9E"}