@beingmartinbmc/ojas 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,1115 @@
+/**
+ * Ojas — AI Health Infrastructure for Autonomous Agents
+ *
+ * Core type definitions shared across all modules:
+ *   - Aahar (Cognitive Nutrition)
+ *   - Nidra (Recovery & Consolidation)
+ *   - Vyayam (Resilience & Stress Engineering)
+ */
+export type HealthScoreBasis = 'heuristic' | 'synthetic_calibrated' | 'empirical_calibrated';
+export interface HealthScore {
+    /** 0.0 (critical) to 1.0 (optimal) */
+    value: number;
+    /** ISO timestamp of measurement */
+    timestamp: string;
+    /** What produced this score */
+    source: string;
+    /**
+     * Evidence basis for interpreting the score. Heuristic scores are advisory
+     * diagnostics; calibrated scores still need their sample provenance before
+     * anyone treats them as probabilities.
+     */
+    basis?: HealthScoreBasis;
+    /** Number of calibration samples behind the score, when known. */
+    calibrationSampleSize?: number;
+    /** Short operator-facing interpretation of what the score can and cannot mean. */
+    interpretation?: string;
+}
+export type OjasModuleName = 'aahar' | 'nidra' | 'vyayam' | 'raksha' | 'agni' | 'pulse' | 'chikitsa';
+export interface AgentHealthReport {
+    agentId: string;
+    timestamp: string;
+    overall: HealthScore;
+    /** Per-module breakdown of health scores on a 0–100 scale. */
+    moduleScores: ModuleScoreBreakdown;
+    nutrition: NutritionHealth;
+    recovery: RecoveryHealth;
+    resilience: ResilienceHealth;
+    defense: DefenseHealth;
+    metabolism: MetabolismHealth;
+    telemetry: TelemetryHealth;
+    rehabilitation: RehabilitationHealth;
+    recommendations: readonly HealthRecommendation[];
+    events: readonly HealthEvent[];
+    /**
+     * Repair protocols that Chikitsa would emit for the failures detected
+     * during this health check. These are previews — not stored — so the
+     * report stays idempotent. Call `ojas.chikitsa.diagnose(failures)`
+     * explicitly to persist them.
+     */
+    previewRepairProtocols: readonly RepairProtocol[];
+}
+/**
+ * Per-module 0–100 health scores in the canonical "Agent Health Score" format.
+ * Matches the Ojas spec example: Aahar 87, Nidra 78, Vyayam 74, etc.
+ */
+export interface ModuleScoreBreakdown {
+    aahar: number;
+    nidra: number;
+    vyayam: number;
+    raksha: number;
+    agni: number;
+    pulse: number;
+    chikitsa: number;
+}
+export interface HealthRecommendation {
+    module: OjasModuleName;
+    severity: 'info' | 'warning' | 'critical';
+    message: string;
+    action?: string;
+}
+export interface HealthEvent<TDetails extends Record<string, unknown> = Record<string, unknown>> {
+    id: string;
+    eventType: string;
+    agentId: string;
+    timestamp: string;
+    severity: 'info' | 'warning' | 'critical';
+    detectedBy: OjasModuleName;
+    details: TDetails;
+    recommendedAction?: string;
+}
+export interface ContextItem {
+    id: string;
+    content: string;
+    source: string;
+    /**
+     * Optional on-demand content resolver. When provided, `content`
+     * acts as a placeholder used for sizing / scoring and the real
+     * payload is fetched only after `Aahar.filter()` decides to accept
+     * the item — surface it via `aahar.materialise(filtered)` to await
+     * resolution lazily. Useful when content is expensive to compute
+     * (DB queries, remote fetches) and you'd rather not pay the cost
+     * for items the budget might drop. The resolver MUST return a
+     * string; throwing rejects the item from the materialised output.
+     */
+    resolveContent?: () => string | Promise<string>;
+    relevanceScore: number;
+    freshness: number;
+    tokenCount: number;
+    metadata?: Record<string, unknown>;
+    trustScore?: number;
+    sensitivity?: 'public' | 'internal' | 'confidential' | 'secret';
+    /**
+     * Loading tier hint for Aahar's progressive-loading filter.
+     * Three-tier split:
+     *   - `'always'`  — Tier 1: never dropped by tier filtering;
+     *   - `'on-demand'` — Tier 2: dropped only when budget is tight;
+     *   - `'rare'` — Tier 3: dropped first when budget is tight.
+     * Optional. When absent, Aahar treats the item as `'on-demand'`,
+     * which preserves the legacy single-pool behaviour.
+     */
+    tier?: 'always' | 'on-demand' | 'rare';
+}
+export interface NutritionHealth {
+    contextQuality: HealthScore;
+    cognitiveLoad: HealthScore;
+    attentionFocus: HealthScore;
+    signalToNoise: number;
+    tokenEfficiency: number;
+}
+export interface NutritionPolicy {
+    /** Max tokens allowed in active context */
+    maxContextTokens: number;
+    /** Minimum relevance score to include (0-1) */
+    relevanceThreshold: number;
+    /** Max age in seconds before context is considered stale */
+    freshnessWindowSec: number;
+    /** Maximum number of context items */
+    maxContextItems: number;
+    /** Target signal-to-noise ratio */
+    targetSignalToNoise: number;
+    /** Hard cap on retained Aahar filter history. */
+    maxHistory?: number;
+    /**
+     * Temporal intent for ranking and the freshness gate.
+     *   - `'recent'` (default when undefined): existing behaviour — exponential
+     *     decay favours new items, and items older than `freshnessWindowSec`
+     *     are rejected outright.
+     *   - `'historical'`: invert the decay so older items rank competitively
+     *     against new ones, AND disable the freshness rejection gate (callers
+     *     are deliberately asking about old material).
+     *   - `'any'`: neutralise freshness (constant 0.5) and disable the gate.
+     * The validity check on `freshness` itself (finite Unix-seconds) always
+     * applies regardless of intent — this knob only changes ranking weight
+     * and the staleness reject.
+     */
+    temporalIntent?: 'recent' | 'historical' | 'any';
+    /**
+     * When true, near-duplicate items (Jaccard similarity over 5-shingle
+     * token sets ≥ `deduplicationThreshold`) are collapsed before token-budget
+     * packing — the highest-scored representative survives, the rest go to
+     * `rejected`. Default `false` for backwards compatibility; existing
+     * callers see no behavioural change.
+     */
+    deduplicateNearDuplicates?: boolean;
+    /** Jaccard similarity threshold for `deduplicateNearDuplicates`. Default 0.85. */
+    deduplicationThreshold?: number;
+    /**
+     * Maximal Marginal Relevance lambda for context packing. When `> 0`,
+     * Aahar selects items inside the token budget by balancing score against
+     * dissimilarity to already-picked items: `(1-λ)*score - λ*maxSim`. λ=0
+     * (default) keeps the existing greedy top-K behaviour. λ=1 picks purely
+     * for diversity. A typical value is 0.3–0.5 for coverage-aware retrieval.
+     */
+    diversityWeight?: number;
+}
+/**
+ * Optional per-call inputs for `Aahar.filter` and `Aahar.prioritize`.
+ * When omitted, the call is byte-for-byte equivalent to the previous
+ * single-argument signature.
+ */
+export interface AaharFilterOptions {
+    /**
+     * The active task / user query the agent is trying to satisfy. When
+     * provided, Aahar augments the caller-supplied `relevanceScore` with
+     * on-the-fly BM25 + entity-overlap signals computed against this string
+     * and fuses them via Reciprocal Rank Fusion. The fused signal replaces
+     * the bare relevance term in the ranking score but does NOT bypass the
+     * `relevanceThreshold` gate — the caller's authoritative relevance still
+     * decides admission.
+     */
+    query?: string;
+    /**
+     * Whether to stamp a synthetic `[ojas:omitted N items: <reasons>]`
+     * marker into the returned `accepted` set so the agent has visible
+     * evidence of what was filtered. Default `false` — set `true` for
+     * diagnostics or when you want the agent to know it's looking at a
+     * curated subset (a single synthetic `[ojas:omitted N items: …]`
+     * entry appended to the tail of `accepted`).
+     *
+     * The marker is a synthetic `ContextItem` with
+     * `source: 'aahar/omission'` appended after the genuine accepted
+     * items. It is excluded from the `qualityScore` calculation.
+     */
+    emitOmissionMarker?: boolean;
+}
+/** Tier marking. Per-item via `ContextItem.tier`. */
+export type AaharContextTier = 'always' | 'on-demand' | 'rare';
+export interface FilteredContext {
+    accepted: ContextItem[];
+    rejected: ContextItem[];
+    totalTokens: number;
+    qualityScore: number;
+    /**
+     * Per-tier diagnostic counts so callers can see how the tier filter
+     * affected the input. Only populated when at least one item carried a
+     * `tier` hint via `AaharFilterOptions.tier`.
+     */
+    tierBreakdown?: Record<AaharContextTier, {
+        accepted: number;
+        rejected: number;
+    }>;
+}
+export type RuntimeFailureType = 'tool_error' | 'timeout' | 'hallucination' | 'policy_violation' | 'retrieval_noise' | 'loop' | 'prompt_injection' | 'unknown';
+export interface RuntimeFailure {
+    type: RuntimeFailureType;
+    message: string;
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    metadata?: Record<string, unknown>;
+}
+export interface ExecutionTrace {
+    id: string;
+    agentId: string;
+    timestamp: string;
+    action: string;
+    input: unknown;
+    output: unknown;
+    success: boolean;
+    /** Authoritative wall-clock duration measured by the host (Ojas), not the agent. */
+    durationMs: number;
+    reasoning?: string;
+    error?: string;
+    failures?: RuntimeFailure[];
+    /** Total tokens consumed by this step (sum of input + output + reasoning). */
+    tokensUsed?: number;
+    /** Tokens consumed by the input/prompt portion if the agent reports it separately. */
+    inputTokens?: number;
+    /** Tokens consumed by the output portion if the agent reports it separately. */
+    outputTokens?: number;
+    /** Number of tool calls invoked during this step. */
+    toolCalls?: number;
+    /** Reported cost in USD when available (e.g. from a model gateway). */
+    costUsd?: number;
+}
+export type MemoryHealthStatus = 'active' | 'candidate' | 'quarantined' | 'expired' | 'rejected';
+/**
+ * Memory kind taxonomy — a three-category split:
+ *  - `'procedural'` — a learned rule or operating instruction
+ *    (e.g. *"Action X is reliable, prefer for similar tasks"*). This is
+ *    the default kind for cluster-derived memories produced by
+ *    `Nidra.runRecoveryCycle()` because the heuristic encodes an
+ *    action-level rule.
+ *  - `'episodic'` — a specific past experience preserved as a learning
+ *    example, with situation / reasoning / outcome. Reserved for a
+ *    future hot-path `recordInsight()` API.
+ *  - `'semantic'` — a fact about the world / user / domain. Reserved for
+ *    opt-in LLM-extracted memories; no built-in producer today.
+ */
+export type ConsolidatedMemoryKind = 'procedural' | 'episodic' | 'semantic';
+export interface ConsolidatedMemory {
+    id: string;
+    /**
+     * Memory kind. Defaults to `'procedural'` for cluster-derived memories.
+     * See `ConsolidatedMemoryKind` for the taxonomy and rationale.
+     */
+    kind?: ConsolidatedMemoryKind;
+    /**
+     * Ingestion time: when consolidation produced this memory.
+     * Paired with `observedAt` (event time) to form a bi-temporal
+     * record (ingestion time + event time).
+     */
+    createdAt: string;
+    /**
+     * Event time: the timestamp of the earliest source trace this memory
+     * was distilled from. `undefined` when the memory has no traceable
+     * source (e.g. injected by tests). Drift analysis and time-travel
+     * queries care about this clock; audit / replay cares about
+     * `createdAt`.
+     */
+    observedAt?: string;
+    /**
+     * When this memory stopped being authoritative, in ISO-8601 UTC.
+     * `undefined` means it is still active. Set by `Nidra.commitAnalysis()`
+     * when a later memory with the same kind + overlapping applicability
+     * and a materially different confidence supersedes this one.
+     * Memories are *invalidated, not deleted* so the audit trail and
+     * historical queries survive. Use `Nidra.getActiveMemories()` or
+     * `Nidra.findMemories({ asOf })` to filter.
+     */
+    invalidatedAt?: string;
+    /**
+     * ID of the `ConsolidatedMemory` that replaced this one. Only set
+     * when `invalidatedAt` is also set. Lets dashboards / auditors
+     * follow the chain of belief revision back to its current head.
+     */
+    supersededBy?: string;
+    sourceTraces: string[];
+    heuristic: string;
+    confidence: number;
+    applicability: string[];
+    abstraction: string;
+    riskScore?: number;
+    verified?: boolean;
+    expiresAt?: string;
+    healthStatus?: MemoryHealthStatus;
+    source?: string;
+    lastUsedAt?: string;
+    freshness?: number;
+    usefulness?: number;
+    redundancyScore?: number;
+    expiryPolicy?: string;
+    allowedContexts?: string[];
+    /**
+     * Provenance quality. `'full'` means every entry in `sourceTraces` is
+     * still retained and inspectable via `Nidra.getTraces()`. `'degraded'`
+     * means one or more source traces were evicted by retention between
+     * analyse and commit — the memory itself is committed because the
+     * analysis already encoded what those traces meant, but operators
+     * cannot drill back into the raw evidence. `sourceTracesEvicted`
+     * lists exactly which IDs are no longer retrievable.
+     */
+    provenance?: 'full' | 'degraded';
+    /** Subset of `sourceTraces` that had been evicted by retention at commit time. */
+    sourceTracesEvicted?: string[];
+    /**
+     * Optional structural type of the memory node. `text` is the
+     * default for free-form heuristics; the other values let callers
+     * index / scan memory faster by node kind. Additive — existing
+     * memories without a `nodeType` continue to work.
+     */
+    nodeType?: MemoryNodeType;
+    /**
+     * Read-temperature in [0, 1]. Rises when the memory is accessed
+     * (e.g. via `Nidra.touchMemory(id)`) and decays exponentially over
+     * time. Hot memories rank higher in search; cold memories cross a
+     * threshold and trigger a `memory_cold` Pulse event so the agent can
+     * compact them. Optional — undefined means "untracked, treat as warm".
+     */
+    temperature?: number;
+    /**
+     * UTC ISO timestamp of the most recent temperature update. Used to
+     * compute decay since the last read.
+     */
+    temperatureUpdatedAt?: string;
+}
+/**
+ * Structural node types for `ConsolidatedMemory.nodeType`. We use
+ * plain strings rather than an enum so the JSON shape is
+ * human-readable and the field is easy to filter on. Add new types
+ * here when they're genuinely distinct from the existing ones —
+ * duplication forces a schema migration.
+ */
+export type MemoryNodeType = 'heading' | 'list' | 'kv' | 'table' | 'preamble' | 'text' | 'code' | 'embed';
+/**
+ * Cursor handed back by `Nidra.getMemoryCursor()` and accepted by
+ * `Nidra.getMemoryDelta(cursor)`. Opaque to callers — treat it as a
+ * black-box token. The hash collapses the current memory-set
+ * fingerprint so the server can detect that nothing has changed
+ * since the cursor was issued.
+ */
+export interface MemoryCursor {
+    /** Hash over the current memory set (stable identifier of "where we were"). */
+    cursorHash: string;
+    /** UTC ISO timestamp when the cursor was issued. Informational, not enforced. */
+    issuedAt: string;
+}
+/**
+ * Delta returned by `Nidra.getMemoryDelta(cursor)`. The agent
+ * passes its last cursor, gets back only the memories that have
+ * been added or modified since, plus a new cursor for the next
+ * round. A whole-tree re-fetch is an explicit decision
+ * (`fullResync: true`).
+ */
+export interface MemoryDelta {
+    /** Memories newly committed since the supplied cursor. */
+    added: ConsolidatedMemory[];
+    /** Memories whose content / status changed since the supplied cursor. */
+    modified: ConsolidatedMemory[];
+    /** IDs of memories that have been pruned since the supplied cursor. */
+    removedIds: string[];
+    /** The new cursor — pass this to the next `getMemoryDelta` call. */
+    nextCursor: MemoryCursor;
+    /**
+     * `true` when the supplied cursor was so old (or never existed) that
+     * we cannot represent the delta accurately. Caller should treat
+     * `added` as the full memory set and discard any local cache.
+     */
+    fullResync: boolean;
+}
+export interface RecoveryHealth {
+    memoryConsolidation: HealthScore;
+    cognitiveStability: HealthScore;
+    learningRate: HealthScore;
+    driftScore: number;
+    lastRecoveryCycle: string | null;
+}
+export interface RecoveryPolicy {
+    /** Minimum traces before consolidation triggers */
+    minTracesForConsolidation: number;
+    /** How often to run recovery cycles (seconds) */
+    recoveryIntervalSec: number;
+    /** Max drift score before forced recovery */
+    maxDriftThreshold: number;
+    /** Number of recent failures to analyze */
+    failureWindowSize: number;
+    /** Confidence threshold for memory retention */
+    retentionConfidence: number;
+    /**
+     * Minimum absolute change in `confidence` between a new memory and an
+     * existing active one (same kind + overlapping applicability) before
+     * the existing memory is treated as superseded and marked
+     * `invalidatedAt`. Defaults to `0.15` (15 percentage points). Set to
+     * `0` to supersede on ANY new same-pattern memory; set to `1` to
+     * disable supersession entirely.
+     */
+    supersessionConfidenceDelta?: number;
+    /** Hard cap on retained trace count; oldest are evicted when exceeded. */
+    maxTraces?: number;
+    /** Hard cap on retained consolidated memories. */
+    maxMemories?: number;
+    /** Hard cap on retained processed-trace IDs (matches maxTraces by default). */
+    maxProcessedTraceIds?: number;
+    /** Hard cap on recovery cycles retained in history. */
+    maxCycleHistory?: number;
+    /**
+     * Memory-temperature half-life in seconds. After this much time
+     * without access, a memory's temperature halves. Default 7 days
+     * (`7 * 24 * 60 * 60`). Set very large to effectively disable
+     * decay, or very small to make memories cool aggressively.
+     */
+    temperatureHalfLifeSec?: number;
+    /**
+     * Increment applied to a memory's temperature each time it is read
+     * via `Nidra.touchMemory(id)`. Default `0.25` (one read warms a
+     * memory by 25%, capped at 1.0). Set to 0 to disable touch-based
+     * heating entirely.
+     */
+    temperatureBoostOnTouch?: number;
+    /**
+     * Threshold below which a memory is considered "cold". When a memory
+     * crosses this threshold on the next `assess()` pass, a
+     * `memory_cold` Pulse event is emitted once per crossing so the
+     * agent can choose to compact / summarise. Default `0.15`.
+     */
+    coldTemperatureThreshold?: number;
+}
+export interface RecoveryCycleResult {
+    cycleId: string;
+    startedAt: string;
+    completedAt: string;
+    tracesProcessed: number;
+    memoriesConsolidated: ConsolidatedMemory[];
+    patternsIdentified: string[];
+    driftReduction: number;
+    healthBefore: RecoveryHealth;
+    healthAfter: RecoveryHealth;
+    /**
+     * Whether this is a pure preview (no state mutated) or a committed
+     * recovery cycle. **Required** — consumers must branch on this rather
+     * than treating `healthAfter` as ground truth in both cases.
+     */
+    mode: 'preview' | 'committed';
+    /**
+     * True when `healthAfter` is an estimate (preview) rather than a
+     * post-mutation measurement (committed). **Required** so dashboards
+     * cannot accidentally graph preview numbers as real recovery deltas.
+     */
+    healthAfterEstimated: boolean;
+    /**
+     * How many of the analysis's covered trace IDs were still in the trace
+     * store at commit time. Only meaningful on a `'committed'` result;
+     * undefined on previews. Useful for detecting that a long delay
+     * between analyse and commit caused some source traces to age out.
+     */
+    coveredTracesRetained?: number;
+    /**
+     * How many covered trace IDs had been evicted by retention between
+     * analyse and commit. When non-zero, the consolidated memories may
+     * reference traces that no longer appear in `getTraces()`.
+     */
+    coveredTracesEvicted?: number;
+    /**
+     * IDs of pre-existing memories that this cycle invalidated by
+     * supersession. Each such memory now has `invalidatedAt` set and
+     * `supersededBy` pointing into `memoriesConsolidated`. On `'preview'`
+     * results this lists what WOULD be invalidated if the analysis were
+     * committed — populated without any mutation. Empty / `undefined`
+     * when no candidate prior memory met the confidence-delta threshold.
+     */
+    supersededMemoryIds?: string[];
+}
+/**
+ * Output of `Nidra.analyseUnprocessed()`. A precomputed analysis envelope
+ * that can be inspected, used to inject memories into an agent, and then
+ * passed to `Nidra.commitAnalysis()` — yielding transactional recovery
+ * where Ojas's internal state only changes if the side-effecting steps
+ * (e.g. `agent.injectMemory()`) all succeeded.
+ */
+export interface RecoveryAnalysis {
+    cycleId: string;
+    startedAt: string;
+    tracesProcessed: number;
+    coveredTraceIds: string[];
+    memories: ConsolidatedMemory[];
+    patterns: string[];
+    healthBefore: RecoveryHealth;
+    estimatedHealthAfter: RecoveryHealth;
+    driftBefore: number;
+}
+export type ThreatType = 'prompt_injection' | 'instruction_override' | 'data_exfiltration' | 'tool_misuse' | 'memory_poisoning' | 'role_confusion' | 'unknown';
+export interface ThreatAssessment {
+    itemId: string;
+    threatType: ThreatType;
+    riskScore: number;
+    quarantined: boolean;
+    reasons: string[];
+    detectedBy?: string;
+}
+export interface PromptInjectionDetectorInput {
+    item: ContextItem;
+    normalizedContent: string;
+    expandedContent?: string;
+    scanTarget: string;
+}
+export interface PromptInjectionAssessment {
+    threatType: ThreatType;
+    riskScore: number;
+    reasons: string[];
+    detectedBy: string;
+}
+export interface PromptInjectionDetector {
+    readonly name: string;
+    detect(input: PromptInjectionDetectorInput): PromptInjectionAssessment;
+}
+/**
+ * Async, ML-backed prompt injection classifier.
+ * Unlike the synchronous `PromptInjectionDetector` (regex/pattern),
+ * classifiers may call external services or run ONNX models.
+ * Raksha runs classifiers *after* its deterministic stack and merges
+ * the highest probability.
+ */
+export interface PromptInjectionClassifier {
+    readonly name: string;
+    classify(text: string, signal?: AbortSignal): Promise<ClassifierResult>;
+}
+export interface ClassifierResult {
+    injectionProbability: number;
+    label: 'safe' | 'injection' | 'unknown';
+    meta?: Record<string, unknown>;
+}
+export interface DefenseHealth {
+    threatResistance: HealthScore;
+    instructionIntegrity: HealthScore;
+    quarantineEffectiveness: HealthScore;
+    threatsDetected: number;
+    quarantinedItems: number;
+}
+export interface DefensePolicy {
+    quarantineThreshold: number;
+    warnThreshold: number;
+    protectInstructionHierarchy: boolean;
+    /** Hard cap on retained threat assessments. */
+    maxAssessments?: number;
+    /** Hard cap on retained Raksha events. */
+    maxEvents?: number;
+}
+export interface MetabolismHealth {
+    tokenEfficiency: HealthScore;
+    toolEconomy: HealthScore;
+    reasoningEfficiency: HealthScore;
+    latencyEfficiency: HealthScore;
+    costPressure: number;
+}
+export interface MetabolismPolicy {
+    targetTokensPerTask: number;
+    maxLatencyMs: number;
+    maxToolCallsPerTask: number;
+    highRiskReasoningBoost: number;
+    /** Hard cap on retained metabolism traces. */
+    maxTraces?: number;
+    /** Optional target cost per task in USD when cost telemetry is available. */
+    targetCostUsdPerTask?: number;
+}
+/**
+ * Pluggable hallucination detector. Plugs into Raksha to score the
+ * likelihood that an agent's **output** contains hallucination — i.e.
+ * claims not grounded in the supplied retrieval context, or claims
+ * that disagree across alternative samples of the same prompt.
+ *
+ * This is a deliberately small, dep-free interface. Built-in
+ * implementations include:
+ *   - `BestOfNInconsistencyDetector` — black-box consistency via
+ *     n-gram overlap across alternative samples of the same prompt.
+ *   - `ClaimLevelDetector` — sentence-level grounding check against
+ *     retrieved context, n-gram based, no ML.
+ *   - `AbstentionDetector` — recognises "I don't know" / hedging
+ *     patterns and surfaces them as *positive* (calibrated) signal.
+ *
+ * Heavier external adapters (encoder-grounding models, LLM judge
+ * panels, etc.) can implement this same interface; Ojas core does
+ * not depend on any of them.
+ *
+ * Implementations MUST NOT throw — return a low-confidence assessment
+ * with a clear `reason` on internal error. Raksha's wrapper guards
+ * against thrown errors but that's a defence-in-depth check.
+ */
+export interface HallucinationDetector {
+    /** Stable identifier for telemetry / report stamping (e.g. `bestofn/n-gram`). */
+    readonly name: string;
+    /** Score the likelihood that `output` contains hallucination. MUST NOT throw. */
+    detect(input: HallucinationDetectorInput): Promise<HallucinationAssessment>;
+}
+export interface HallucinationDetectorInput {
+    /** The agent's output text under evaluation. */
+    output: string;
+    /**
+     * Alternative responses sampled from the same prompt. Required for
+     * consistency-based scoring; ignored by claim-level / abstention
+     * detectors. Pass an empty array to indicate "single generation".
+     */
+    samples?: string[];
+    /**
+     * Retrieved context the output was supposed to be grounded in. Used
+     * by claim-level detectors to check each sentence-claim against the
+     * provided context. Pass an empty array for "no grounding source".
+     */
+    context?: string[];
+    /** Optional task / prompt for which this output was generated. */
+    prompt?: string;
+}
+export interface ClaimAssessment {
+    /** The claim text (typically a sentence). */
+    claim: string;
+    /** Risk in [0, 1]. 0 = well-grounded, 1 = unsupported by context. */
+    riskScore: number;
+    /** IDs / indices of context entries that grounded this claim, if any. */
+    groundedIn?: string[];
+}
+export interface HallucinationAssessment {
+    /** Overall risk score in [0, 1]. 0 = grounded / consistent, 1 = likely hallucinated. */
+    riskScore: number;
+    /**
+     * Detector's confidence in this score, in [0, 1]. Low when the
+     * detector lacked the inputs it needs (e.g. no samples for a
+     * consistency detector). Operators should weight risk by confidence.
+     */
+    confidence: number;
+    /** Stable detector identifier (matches `HallucinationDetector.name`). */
+    detectedBy: string;
+    /** Short human-readable reasons that contributed to the score. */
+    reasons: string[];
+    /** Per-claim breakdown when the detector is claim-level. */
+    claims?: ClaimAssessment[];
+    /** Whether the output looks like an appropriate abstention (e.g. "I don't know"). */
+    abstention?: boolean;
+}
+/**
+ * Pluggable model router. Plugs into Agni to recommend cheaper /
+ * faster model routes for task classes where observed outcome data
+ * supports it. Pattern: observe pass/fail per task class, only route
+ * cheap when the lower bound of the 95% confidence interval on
+ * success rate exceeds a configured threshold (fail-closed under
+ * sparse data).
+ *
+ * Ojas ships `ConfidenceRoutingTable` as the default; it never calls
+ * an LLM itself. Callers wire the recommendation to their own provider
+ * gateway.
+ */
+export interface ModelRouter {
+    readonly name: string;
+    /** Record an observed outcome for a task class. */
+    recordOutcome(taskClass: string, succeeded: boolean): void;
+    /** Recommend a routing decision for `taskClass`. */
+    recommend(taskClass: string): ModelRouterDecision;
+    /** Stable snapshot of what the router has learned. */
+    report(): ReadonlyArray<ModelRouterTaskReport>;
+}
+export interface ModelRouterDecision {
+    /** `'cheap'` to route to the cheaper / faster model; `'flagship'` to keep the default. */
+    route: 'cheap' | 'flagship';
+    /** Why this decision was made (human-readable, for logging). */
+    reason: string;
+    /** Number of observations the decision is based on. */
+    n: number;
+    /** 95% CI on success rate for this task class, [lo, hi]. `null` for n=0. */
+    successCI?: {
+        lo: number;
+        hi: number;
+    } | null;
+}
+export interface ModelRouterTaskReport {
+    taskClass: string;
+    n: number;
+    successes: number;
+    successRate: number;
+    successCI: {
+        lo: number;
+        hi: number;
+    } | null;
+    currentRoute: 'cheap' | 'flagship';
+}
+/**
+ * Pluggable response distiller. Plugs into Agni to strip filler from
+ * an agent's *output* (preserves code blocks). Default implementation:
+ * `defaultResponseDistiller` (rule-based, three intensity levels).
+ *
+ * Callers can swap in a learned distiller (e.g. a small LM trained on
+ * filler corpora) by implementing this interface.
+ */
+export interface ResponseDistiller {
+    readonly name: string;
+    /** Distill `text` to remove non-load-bearing content. Preserve code blocks. */
+    distill(text: string): ResponseDistillResult;
+}
+export interface ResponseDistillResult {
+    /** The distilled text. */
+    text: string;
+    /** Number of tokens removed (estimated). */
+    tokensRemoved: number;
+    /**
+     * Exact number of characters removed across the per-pattern passes.
+     * Useful for monitoring distiller aggressiveness without depending on
+     * the char/4 token estimate. Always `>= 0` and `<= text.length`.
+     */
+    charsRemoved: number;
+    /** What kinds of removal happened (`preamble`, `hedging`, `meta`, `closer`). */
+    removed: string[];
+}
+/**
+ * Pluggable token estimator. Used by Agni when a trace did not supply
+ * explicit `tokensUsed` / `inputTokens` / `outputTokens` telemetry — i.e.
+ * for the fallback path.
+ *
+ * Implementations must:
+ *   - never throw (return a numeric fallback on internal error);
+ *   - return a non-negative integer;
+ *   - expose a stable `name` for telemetry / report stamping.
+ *
+ * The Ojas default is `charBasedTokenEstimator` (char/4, conservative,
+ * platform-stable). Real-tokenizer adapters live in `src/agni/`:
+ *   - `createTiktokenEstimator('cl100k_base')` (requires the optional
+ *     `tiktoken` package to be installed by the host project).
+ */
+export interface TokenEstimator {
+    /** Stable identifier for telemetry / report stamping (e.g. 'char/4'). */
+    readonly name: string;
+    /** Estimate tokens for a piece of text. MUST NOT throw. */
+    estimate(text: string): number;
+}
+export interface TelemetryHealth {
+    vitalSigns: HealthScore;
+    degradationRisk: HealthScore;
+    observabilityCoverage: HealthScore;
+    eventsEmitted: number;
+    activeAlerts: number;
+}
+export interface TelemetryPolicy {
+    maxRecentEvents: number;
+    degradationThreshold: number;
+    /**
+     * Trailing window size for latency percentile tracking, per
+     * `(agentId, taskClass)`. Default 100. Older samples are dropped so
+     * memory usage is stable in long-running processes.
+     */
+    latencyWindowSize?: number;
+    /**
+     * Optional latency budget in ms. If set, `recordLatency()` emits a
+     * `latency_breach` event when the windowed p95 exceeds this value
+     * (idempotent per `(agentId, taskClass)` until the percentile drops
+     * back below the budget — clears the latch). Default unset (no
+     * automatic breach detection).
+     */
+    latencyP95BreachMs?: number;
+    /**
+     * How long an agent can go without a `heartbeat()` before
+     * `detectStuckAgents()` flags it and Pulse emits `agent_stuck`.
+     * Default 60_000 (60 s).
+     */
+    stuckAfterMs?: number;
+}
+/**
+ * Windowed latency summary for one `(agentId, taskClass)` pair.
+ * Returned by `Pulse.getLatencyStats()`. All durations are in
+ * milliseconds.
+ */
+export interface LatencyStats {
+    agentId: string;
+    taskClass: string;
+    samples: number;
+    /** Average duration. */
+    meanMs: number;
+    /** 50th percentile (median). */
+    p50Ms: number;
+    /** 95th percentile. */
+    p95Ms: number;
+    /** Maximum observed in window. */
+    maxMs: number;
+}
+/**
+ * Snapshot of one stuck-agent flag, returned by
+ * `Pulse.detectStuckAgents()`. `agent_stuck` events are also emitted
+ * once per (agentId, idle-window) crossing.
+ */
+export interface StuckAgentReport {
+    agentId: string;
+    /** Last observed heartbeat in ISO-8601 UTC, if ever recorded. */
+    lastHeartbeatAt?: string;
+    /** Milliseconds since `lastHeartbeatAt` at the time of the call. */
+    idleMs: number;
+}
+export type RepairAction = 'context_reset' | 'memory_rollback' | 'tool_retry' | 'plan_regeneration' | 'retrieval_refresh' | 'instruction_regrounding' | 'safe_mode_activation' | 'human_escalation';
+export interface RepairProtocol {
+    id: string;
+    diagnosis: string;
+    actions: RepairAction[];
+    severity: 'info' | 'warning' | 'critical';
+}
+/**
+ * Pluggable executor for repair protocols. Chikitsa diagnoses
+ * failures and produces `RepairProtocol`s but does **not** execute
+ * them — execution is the caller's responsibility because the
+ * concrete action (resetting a context window, retrying a tool,
+ * activating safe mode) is runtime-specific.
+ *
+ * Implementations MUST be idempotent on `protocol.id`: calling
+ * `execute()` twice with the same id must not double-apply effects.
+ * Chikitsa tracks per-id state and short-circuits a second call, but
+ * a defensive implementation is recommended.
+ *
+ * Implementations MUST NOT throw — return `{ status: 'failed', … }`
+ * and let Chikitsa decide whether to attempt rollback. A thrown
+ * error is caught by Chikitsa and recorded as `status: 'failed'`.
+ */
+export interface RepairExecutor {
+    readonly name: string;
+    execute(protocol: RepairProtocol): Promise<RepairExecutionResult>;
+    /** Optional compensating action. Called by Chikitsa when verification fails. */
+    rollback?(protocol: RepairProtocol, executionDetails: Record<string, unknown>): Promise<void>;
+}
+export interface RepairExecutionResult {
+    status: 'applied' | 'failed';
+    /** Free-form executor-specific payload (e.g. tool retry count, reset hash). */
+    details: Record<string, unknown>;
+    /** Optional human-readable summary. */
+    message?: string;
+}
+/**
+ * Pluggable verifier called by Chikitsa after `RepairExecutor.execute()`
+ * succeeds. Closes the detect → diagnose → repair → verify loop so
+ * the agent has evidence the repair actually fixed the failure.
+ *
+ * Implementations MUST NOT throw — return `{ verified: false, … }`
+ * on any internal error.
+ */
+export interface RepairVerifier {
+    readonly name: string;
+    verify(protocol: RepairProtocol, executionResult: RepairExecutionResult): Promise<RepairVerificationResult>;
+}
+export interface RepairVerificationResult {
+    verified: boolean;
+    /** Why we believe the repair worked (or didn't). */
+    reason: string;
+    /** Confidence in `[0, 1]`. */
+    confidence: number;
+}
+/**
+ * Record of one execute-then-verify cycle. Returned by
+ * `Chikitsa.executeProtocol()` and retained in
+ * `Chikitsa.executionHistory()` for audit.
+ */
+export interface RepairExecutionRecord {
+    protocolId: string;
+    startedAt: string;
+    finishedAt: string;
+    /**
+     * Terminal status of the cycle:
+     *  - `'verified'`     — execute succeeded AND verifier returned true
+     *  - `'applied'`      — execute succeeded; no verifier configured
+     *  - `'unverified'`   — execute succeeded; verifier returned false
+     *  - `'rolled-back'`  — verifier returned false AND executor's `rollback()` ran
+     *  - `'failed'`       — execute returned `failed` or threw
+     *  - `'already-applied'` — second call for an already-applied protocol id
+     */
+    status: 'verified' | 'applied' | 'unverified' | 'rolled-back' | 'failed' | 'already-applied';
+    executor: string;
+    verifier?: string;
+    executionResult?: RepairExecutionResult;
+    verificationResult?: RepairVerificationResult;
+    /** Captured error message when status === 'failed' because of a throw. */
+    error?: string;
+}
+export interface RehabilitationHealth {
+    repairReadiness: HealthScore;
+    rollbackSafety: HealthScore;
+    recoveryPlaybooks: HealthScore;
+    protocolsAvailable: number;
+}
+/**
+ * One observed agent task outcome, fed to Chikitsa via
+ * `recordTaskOutcome(...)`. Drives the velocity / success-rate
+ * windowed statistics surfaced in `getVelocityStats()`.
+ */
+export interface TaskOutcomeRecord {
+    /** Stable ID for the task. Deduping is *not* enforced. */
+    taskId: string;
+    /** When the task completed (or was abandoned). */
+    completedAt: string;
+    /** Whether the task ultimately succeeded. */
+    succeeded: boolean;
+    /** Wall-clock duration in ms; required for throughput. */
+    durationMs: number;
+    /** Optional category — e.g. `'investigation'`, `'feature'`, `'bug'`. */
+    category?: string;
+}
+/**
+ * Windowed velocity summary returned by `Chikitsa.getVelocityStats()`.
+ * Reflects only the trailing `velocityWindowSize` outcomes (default 50).
+ */
+export interface VelocityStats {
+    /** Number of outcomes in the rolling window. */
+    windowSize: number;
+    /** Fraction of those that succeeded (0 if window is empty). */
+    successRate: number;
+    /** Median duration over the window, in ms (0 if empty). */
+    medianDurationMs: number;
+    /** P90 duration over the window, in ms (0 if empty). */
+    p90DurationMs: number;
+    /**
+     * Tasks-per-hour computed from total successes / span between the
+     * oldest and newest `completedAt` in the window. Returns 0 if the
+     * span is undefined (single sample) or the window is empty.
+     */
+    tasksPerHour: number;
+}
+/**
+ * Snapshot of agent state that Chikitsa serialises into a Markdown
+ * handoff document via `generateHandoff()`. Lets one agent / session
+ * pick up exactly where the previous left off (a structured
+ * `progress.txt`-style cross-session resume artefact).
+ */
+export interface HandoffSnapshot {
+    /** Agent identifier (`OjasConfig.agentId`). */
+    agentId: string;
+    /** When this snapshot was generated. */
+    generatedAt: string;
+    /** Free-text current focus / objective. */
+    focus?: string;
+    /** Open items the next agent should address. */
+    pendingTasks: string[];
+    /** Completed items, kept brief for context. */
+    completedTasks: string[];
+    /** Velocity stats embedded at the top of the document. */
+    velocity?: VelocityStats;
+    /** Optional cross-cutting notes. */
+    notes?: string[];
+}
+export interface RehabilitationPolicy {
+    autoRepairEnabled: boolean;
+    criticalRequiresHuman: boolean;
+    maxProtocolsPerCycle: number;
+    /** Hard cap on retained repair protocols. */
+    maxProtocols?: number;
+    /**
+     * Rolling-window size (number of trailing `TaskOutcomeRecord`s)
+     * `getVelocityStats()` summarises. Default 50. Older outcomes are
+     * dropped when this cap is exceeded.
+     */
+    velocityWindowSize?: number;
+}
+export interface StressScenario {
+    id: string;
+    name: string;
+    type: StressType;
+    intensity: number;
+    description: string;
+    payload: unknown;
+}
+export type StressType = 'adversarial_input' | 'latency_spike' | 'conflicting_instructions' | 'memory_corruption' | 'tool_failure' | 'context_overflow' | 'prompt_injection' | 'ambiguous_goal';
+export interface StressTestResult {
+    scenarioId: string;
+    agentId: string;
+    timestamp: string;
+    passed: boolean;
+    hallucinationDetected: boolean;
+    recoveryTimeMs: number;
+    stabilityScore: number;
+    adaptabilityScore: number;
+    details: string;
+}
+export interface ResilienceHealth {
+    overallResilience: HealthScore;
+    hallucinationResistance: HealthScore;
+    recoveryAbility: HealthScore;
+    planningStability: HealthScore;
+    weaknesses: string[];
+}
+export interface ResiliencePolicy {
+    /** How often to run stress tests (seconds) */
+    stressIntervalSec: number;
+    /** Number of scenarios per cycle */
+    scenariosPerCycle: number;
+    /** Minimum resilience score before alerting */
+    minResilienceThreshold: number;
+    /** Enable progressive difficulty */
+    progressiveDifficulty: boolean;
+    /** Max intensity for stress scenarios */
+    maxIntensity: number;
+    /** Hard cap on retained stress-test results. */
+    maxResults?: number;
+    /** Timeout budget per stress scenario in milliseconds. */
+    maxScenarioDurationMs?: number;
+}
+export interface AgentAdapter {
+    id: string;
+    /**
+     * Process input and return output — the agent's core function.
+     * Implementations SHOULD respect the optional `signal` and abort
+     * long-running work when it fires.  Callers that do not supply a
+     * signal get the same behaviour as before (backward-compatible).
+     */
+    process(input: string, context: ContextItem[], signal?: AbortSignal): Promise<AgentResponse>;
+    /** Get current memory/state for health evaluation */
+    getState(): Promise<AgentState>;
+    /** Inject consolidated memory back into agent */
+    injectMemory(memory: ConsolidatedMemory): Promise<void>;
+}
+export interface AgentResponse {
+    output: string;
+    tokensUsed: number;
+    reasoning?: string;
+    confidence: number;
+    durationMs: number;
+}
+export interface AgentState {
+    activeContextSize: number;
+    memoryCount: number;
+    uptime: number;
+    lastActivity: string;
+    errorRate: number;
+}
+export interface OjasConfig {
+    agentId: string;
+    nutrition: NutritionPolicy;
+    recovery: RecoveryPolicy;
+    resilience: ResiliencePolicy;
+    defense: DefensePolicy;
+    metabolism: MetabolismPolicy;
+    telemetry: TelemetryPolicy;
+    rehabilitation: RehabilitationPolicy;
+    /** Enable continuous health monitoring */
+    continuousMonitoring: boolean;
+    /** Health check interval (seconds) */
+    healthCheckIntervalSec: number;
+    /** Hard cap on retained health reports. */
+    maxHealthHistory: number;
+    /**
+     * Pre-fitted calibration model for mapping raw health scores to
+     * empirically calibrated probabilities.  Load from an L3 benchmark
+     * run via `deserializeCalibrationModel()`.  When provided, the
+     * overall health score uses `basis: 'empirical_calibrated'`.
+     */
+    calibrationModel?: import('./util/calibration').IsotonicCalibrationModel;
+}
+export declare const DEFAULT_NUTRITION_POLICY: NutritionPolicy;
+export declare const DEFAULT_RECOVERY_POLICY: RecoveryPolicy;
+export declare const DEFAULT_RESILIENCE_POLICY: ResiliencePolicy;
+export declare const DEFAULT_DEFENSE_POLICY: DefensePolicy;
+export declare const DEFAULT_METABOLISM_POLICY: MetabolismPolicy;
+export declare const DEFAULT_TELEMETRY_POLICY: TelemetryPolicy;
+export declare const DEFAULT_REHABILITATION_POLICY: RehabilitationPolicy;
+export type KnownHealthEventType = 'context_overload_detected' | 'context_items_rejected' | 'recovery_cycle_completed' | 'memory_consolidated' | 'memory_pruned' | 'memory_cold' | 'context_budget_milestone' | 'prompt_injection_quarantined' | 'threat_detected' | 'hallucination_detected' | 'metabolism_pressure_high' | 'stress_test_failed' | 'stress_test_passed' | 'repair_protocol_generated' | 'repair_executed' | 'repair_verified' | 'repair_rolled_back' | 'agent_stuck' | 'latency_breach' | 'degradation_detected' | 'goal_drift_detected';
+export interface ContextOverloadDetectedDetails extends Record<string, unknown> {
+    contextTokens: number;
+    relevanceScore: number;
+    duplicateContextRatio: number;
+}
+export interface RecoveryCycleCompletedDetails extends Record<string, unknown> {
+    rawTracesProcessed: number;
+    memoriesCreated: number;
+    memoriesPruned: number;
+    heuristicsUpdated: number;
+    driftReduction: number;
+}
+export interface PromptInjectionQuarantinedDetails extends Record<string, unknown> {
+    source: string;
+    attackType: ThreatType;
+    riskScore: number;
+    reasons: string[];
+    actionTaken: 'quarantined_from_agent_context' | 'down_ranked' | 'verified';
+}
+export interface MetabolismPressureDetails extends Record<string, unknown> {
+    costPressure: number;
+    avgTokens: number;
+    avgLatencyMs: number;
+    recommendation: 'compress_context' | 'reduce_tool_calls' | 'cap_reasoning_depth';
+}
+export interface StressTestFailedDetails extends Record<string, unknown> {
+    scenarioId: string;
+    stressType: StressType;
+    intensity: number;
+    hallucinationDetected: boolean;
+    stabilityScore: number;
+}
+export interface RepairProtocolGeneratedDetails extends Record<string, unknown> {
+    protocolId: string;
+    diagnosis: string;
+    actions: RepairAction[];
+    failureType: RuntimeFailureType;
+}
+export type ContextOverloadDetectedEvent = HealthEvent<ContextOverloadDetectedDetails>;
+export type RecoveryCycleCompletedEvent = HealthEvent<RecoveryCycleCompletedDetails>;
+export type PromptInjectionQuarantinedEvent = HealthEvent<PromptInjectionQuarantinedDetails>;
+export type MetabolismPressureEvent = HealthEvent<MetabolismPressureDetails>;
+export type StressTestFailedEvent = HealthEvent<StressTestFailedDetails>;
+export type RepairProtocolGeneratedEvent = HealthEvent<RepairProtocolGeneratedDetails>;
+//# sourceMappingURL=types.d.ts.map