@beingmartinbmc/ojas 0.2.0

package/dist/mcp/trace.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Rich trace event taxonomy for the Ojas MCP `ojas_ingest_trace` tool.
+ *
+ * The on-disk Ojas runtime uses a single `ExecutionTrace` shape, but the
+ * MCP boundary accepts a richer event vocabulary so that agents can stream
+ * tool calls, retrievals, memory ops, fallbacks, and policy violations
+ * without flattening everything into a single action label.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyEvent = classifyEvent;
+exports.recommendActionFor = recommendActionFor;
+function readNonNegInt(data, key) {
+    const v = data[key];
+    if (typeof v === 'number' && Number.isFinite(v) && v >= 0 && Number.isInteger(v))
+        return v;
+    return undefined;
+}
+function extractTokenFields(data) {
+    const inputTokens = readNonNegInt(data, 'input_tokens') ?? readNonNegInt(data, 'prompt_tokens');
+    const outputTokens = readNonNegInt(data, 'output_tokens') ?? readNonNegInt(data, 'completion_tokens');
+    let tokensUsed = readNonNegInt(data, 'total_tokens') ?? readNonNegInt(data, 'tokens_used');
+    if (tokensUsed === undefined && (inputTokens !== undefined || outputTokens !== undefined)) {
+        tokensUsed = (inputTokens ?? 0) + (outputTokens ?? 0);
+    }
+    const toolCalls = readNonNegInt(data, 'tool_calls');
+    const cost = data.cost_usd;
+    const costUsd = typeof cost === 'number' && Number.isFinite(cost) && cost >= 0 ? cost : undefined;
+    return {
+        tokens_used: tokensUsed,
+        input_tokens: inputTokens,
+        output_tokens: outputTokens,
+        tool_calls: toolCalls,
+        cost_usd: costUsd,
+    };
+}
+/**
+ * Map a `TraceEventType` + arbitrary payload to the canonical Ojas
+ * `ExecutionTrace` shape plus a set of modules whose state is touched.
+ */
+function classifyEvent(eventType, data = {}) {
+    const toolName = typeof data.tool_name === 'string' ? data.tool_name : null;
+    const errorType = typeof data.error_type === 'string' ? data.error_type : null;
+    const latencyMs = typeof data.latency_ms === 'number' ? data.latency_ms : null;
+    switch (eventType) {
+        case 'tool_call_started':
+            return {
+                meta: { action: toolName ?? 'tool_call', success: true, duration_ms: 0 },
+                affected_modules: ['agni'],
+                health_impact: false,
+            };
+        case 'tool_call_succeeded':
+            return {
+                meta: {
+                    action: toolName ?? 'tool_call',
+                    success: true,
+                    duration_ms: latencyMs ?? 0,
+                    ...extractTokenFields(data),
+                },
+                affected_modules: ['agni', 'pulse'],
+                health_impact: false,
+            };
+        case 'tool_call_failed':
+            return {
+                meta: {
+                    action: toolName ?? 'tool_call',
+                    success: false,
+                    duration_ms: latencyMs ?? 0,
+                    error: errorType ?? 'unknown_failure',
+                    ...extractTokenFields(data),
+                },
+                affected_modules: ['agni', 'pulse', 'chikitsa'],
+                health_impact: true,
+            };
+        case 'retrieval_result':
+            return {
+                meta: { action: 'retrieval', success: true, duration_ms: latencyMs ?? 0 },
+                affected_modules: ['aahar', 'pulse'],
+                health_impact: false,
+            };
+        case 'memory_read':
+            return {
+                meta: { action: 'memory_read', success: true, duration_ms: 0 },
+                affected_modules: ['nidra'],
+                health_impact: false,
+            };
+        case 'memory_write':
+            return {
+                meta: { action: 'memory_write', success: true, duration_ms: 0 },
+                affected_modules: ['nidra', 'raksha'],
+                health_impact: false,
+            };
+        case 'failure':
+            return {
+                meta: {
+                    action: 'failure',
+                    success: false,
+                    duration_ms: 0,
+                    error: typeof data.message === 'string' ? data.message : 'unknown_failure',
+                    ...extractTokenFields(data),
+                },
+                affected_modules: ['chikitsa', 'pulse'],
+                health_impact: true,
+            };
+        case 'latency_measurement':
+            return {
+                meta: { action: 'latency', success: true, duration_ms: latencyMs ?? 0 },
+                affected_modules: ['agni', 'pulse'],
+                health_impact: false,
+            };
+        case 'token_usage':
+            return {
+                meta: {
+                    action: 'token_usage',
+                    success: true,
+                    duration_ms: 0,
+                    ...extractTokenFields(data),
+                },
+                affected_modules: ['agni'],
+                health_impact: false,
+            };
+        case 'user_correction':
+            return {
+                meta: { action: 'user_correction', success: false, duration_ms: 0 },
+                affected_modules: ['nidra', 'pulse'],
+                health_impact: true,
+            };
+        case 'planning_loop':
+            return {
+                meta: {
+                    action: 'planning_loop',
+                    success: false,
+                    duration_ms: 0,
+                    error: 'planning_loop_detected',
+                },
+                affected_modules: ['nidra', 'chikitsa', 'pulse'],
+                health_impact: true,
+            };
+        case 'fallback':
+            return {
+                meta: { action: 'fallback', success: true, duration_ms: 0 },
+                affected_modules: ['chikitsa', 'pulse'],
+                health_impact: false,
+            };
+        case 'policy_violation':
+            return {
+                meta: {
+                    action: 'policy_violation',
+                    success: false,
+                    duration_ms: 0,
+                    error: typeof data.message === 'string' ? data.message : 'policy_violation',
+                },
+                affected_modules: ['raksha', 'chikitsa', 'pulse'],
+                health_impact: true,
+            };
+        case 'prompt_injection_detected':
+            return {
+                meta: {
+                    action: 'prompt_injection_detected',
+                    success: false,
+                    duration_ms: 0,
+                    error: 'prompt_injection',
+                },
+                affected_modules: ['raksha', 'pulse'],
+                health_impact: true,
+            };
+        case 'context_overload_detected':
+            return {
+                meta: {
+                    action: 'context_overload_detected',
+                    success: false,
+                    duration_ms: 0,
+                    error: 'context_overload',
+                },
+                affected_modules: ['aahar', 'pulse'],
+                health_impact: true,
+            };
+        case 'agent_input':
+        case 'agent_output':
+        default:
+            return {
+                meta: {
+                    action: eventType,
+                    success: true,
+                    duration_ms: latencyMs ?? 0,
+                    ...extractTokenFields(data),
+                },
+                affected_modules: ['pulse'],
+                health_impact: false,
+            };
+    }
+}
+/**
+ * Recommend a follow-up Ojas action keyed off the event type. Returned
+ * verbatim in `ojas_ingest_trace`'s response.
+ */
+function recommendActionFor(eventType) {
+    switch (eventType) {
+        case 'tool_call_failed':
+            return 'diagnose_tool_failure';
+        case 'failure':
+        case 'planning_loop':
+            return 'diagnose_failure';
+        case 'prompt_injection_detected':
+            return 'quarantine_and_scan_remaining_inputs';
+        case 'context_overload_detected':
+            return 'compress_context';
+        case 'user_correction':
+            return 'consolidate_memory_with_failure_reflection';
+        case 'policy_violation':
+            return 'enter_safe_mode';
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=trace.js.map

package/dist/mcp/trace.js.map

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

package/dist/nidra/index.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Ojas Nidra (ओजस निद्रा) — AI Recovery & Consolidation System
+ *
+ * Governs how AI agents recover, stabilize, and evolve.
+ * Provides memory consolidation, cognitive recovery,
+ * and reflective learning cycles.
+ */
+import { ExecutionTrace, ConsolidatedMemory, ConsolidatedMemoryKind, MemoryCursor, MemoryDelta, RecoveryHealth, RecoveryPolicy, RecoveryCycleResult, RecoveryAnalysis, HealthRecommendation } from '../types';
+import type { NidraStateSnapshot } from '../persistence/types';
+export declare class Nidra {
+    private policy;
+    private traces;
+    private memories;
+    private cycleHistory;
+    private lastRecovery;
+    /**
+     * Trace IDs that have been processed by a recovery cycle — regardless of
+     * whether they produced a retained memory. Without this set, low-confidence
+     * traces would be reprocessed forever because the prior implementation only
+     * treated a trace as "processed" if it ended up inside a kept memory.
+     */
+    private processedTraceIds;
+    /**
+     * IDs of memories that have already emitted a `memory_cold` event
+     * during the current run, so we don't re-emit on every `assess()`
+     * pass while the temperature stays below the cold threshold.
+     * Cleared when a memory is re-warmed via `touchMemory`.
+     */
+    private coldNotifiedIds;
+    /**
+     * IDs of memories pruned in this Nidra's lifetime, kept so
+     * `getMemoryDelta()` can report them under `removedIds`.
+     * Bounded by `maxProcessedTraceIds` to avoid unbounded growth.
+     */
+    private prunedMemoryIds;
+    constructor(policy?: Partial<RecoveryPolicy>);
+    /**
+     * Mark a memory as accessed: bump its temperature toward `1.0` and
+     * stamp the touch timestamp. Used by agents when they actually read
+     * a memory; `Aahar.filter()` integrations can also call this when a
+     * memory makes it into the context window.
+     *
+     * Returns `true` if the touched memory was previously below the
+     * cold threshold (i.e. the touch *re-warmed* it). Callers may
+     * choose to suppress next-cycle `memory_cold` emission in that case.
+     */
+    touchMemory(id: string): boolean;
+    /**
+     * Current temperature of `id`, with decay applied since the last
+     * touch. Returns `undefined` for unknown memory IDs.
+     */
+    getMemoryTemperature(id: string): number | undefined;
+    /**
+     * Decay model: exponential half-life. Given `temperature` last
+     * updated at `temperatureUpdatedAt`, returns the current decayed
+     * value. The half-life is configurable via
+     * `RecoveryPolicy.temperatureHalfLifeSec` (default one week).
+     */
+    private computeDecayedTemperature;
+    /**
+     * Returns memories whose decayed temperature is now below the cold
+     * threshold. The set is *idempotent across calls* via the
+     * `coldNotifiedIds` set, so this can be called from a periodic
+     * `assess()` pass without spamming the agent.
+     *
+     * The returned shape is the data needed to construct a `memory_cold`
+     * Pulse event; Ojas wires the actual emission in `Ojas.healthCheck()`.
+     */
+    detectColdMemories(): {
+        id: string;
+        temperature: number;
+        abstraction: string;
+    }[];
+    /**
+     * Cursor representing the agent's view of the memory set right now.
+     * The hash collapses a fingerprint of every active memory's
+     * `(id, createdAt, invalidatedAt?, content)` tuple so any change
+     * produces a different cursor.
+     */
+    getMemoryCursor(): MemoryCursor;
+    /**
+     * Return only the memories that changed since `cursor`. If the
+     * cursor is unknown (the agent is calling for the first time, or
+     * its cursor is older than our pruned-id horizon), the response is
+     * a full resync.
+     */
+    getMemoryDelta(cursor?: MemoryCursor): MemoryDelta;
+    /**
+     * Cheap hash for `MemoryCursor.cursorHash`. We just sum a per-memory
+     * fingerprint into a 32-bit accumulator. Not collision-resistant in
+     * the cryptographic sense — but the cursor only needs to detect
+     * "anything changed since last time", and per-id IDs are already
+     * unique.
+     */
+    private computeMemoryHash;
+    /**
+     * Reject malformed RecoveryPolicy fields at the boundary so a buggy
+     * caller can't poison division by `0`, blow up `Math.exp(NaN)`, or
+     * silently disable retention with `-1`.
+     */
+    private validatePolicy;
+    /**
+     * Record an execution trace for later consolidation. Evicts the oldest
+     * traces (and any matching processed-id markers) once the configured
+     * retention cap is hit, so long-running agents stay bounded in memory.
+     */
+    recordTrace(trace: ExecutionTrace): void;
+    /** Record multiple traces at once. */
+    recordTraces(traces: ExecutionTrace[]): void;
+    private enforceTraceRetention;
+    private enforceMemoryAndCycleRetention;
+    /**
+     * Analyse unprocessed traces without committing anything. The returned
+     * envelope can be inspected, passed to `agent.injectMemory()`, and then
+     * finalised via `commitAnalysis()`. This is the building block for
+     * transactional recovery — see `Ojas.recover()` for the canonical use.
+     *
+     * `estimatedHealthAfter` is a forward-looking projection from the same
+     * pre-mutation state; for a true post-state, call `assess()` after
+     * committing.
+     */
+    analyseUnprocessed(): RecoveryAnalysis;
+    /**
+     * Pure preview: returns the memories, patterns, and drift estimate a
+     * commit would produce, with NO mutation. Memories are not appended,
+     * `lastRecovery` is unchanged, no trace IDs are marked processed, and
+     * no cycle is added to history. `healthAfter` is an estimate — for the
+     * true post-commit state, call `runRecoveryCycle()`.
+     *
+     * `supersededMemoryIds` lists the IDs that a commit WOULD invalidate
+     * given current state, so operators can see the impact of running
+     * the cycle without taking the side effect.
+     */
+    previewRecoveryCycle(): RecoveryCycleResult;
+    /**
+     * Commit a precomputed `RecoveryAnalysis`. This is the side-effecting
+     * half of the analyse/commit pair: appends memories, marks traces
+     * processed, updates `lastRecovery`, and records the cycle. Use this
+     * directly to interleave external side effects (e.g. injecting memories
+     * into an agent) between analysis and commit, so a failure in those
+     * side effects leaves Nidra state untouched.
+     *
+     * `healthAfter` is captured AFTER mutation, so `driftReduction`
+     * reflects the real change.
+     *
+     * **Stale-analysis semantics.** Between `analyseUnprocessed()` and
+     * `commitAnalysis()`, new traces may arrive (carried over to next
+     * cycle — fine) AND existing traces may be evicted by retention caps
+     * if the trace store filled up. We mark any covered trace ID as
+     * processed regardless, because the analysis already encoded what
+     * those traces meant. The result reports `coveredTraceIdsStillRetained`
+     * vs `coveredTraceIdsEvicted` so the caller can tell when memories
+     * reference source traces that are no longer in `getTraces()`.
+     */
+    commitAnalysis(a: RecoveryAnalysis): RecoveryCycleResult;
+    /**
+     * Run a full recovery cycle in-process: analyse, then commit. Equivalent
+     * to `commitAnalysis(analyseUnprocessed())`. Convenient when there are
+     * no external side effects to sequence in between.
+     */
+    runRecoveryCycle(): RecoveryCycleResult;
+    /**
+     * Cluster traces by action pattern for consolidation.
+     */
+    private clusterTraces;
+    /**
+     * Convert pattern clusters into consolidated memories.
+     */
+    private consolidateClusters;
+    /**
+     * Pure planning step: compute which existing *active* memories would
+     * be superseded by the given new memories. Does **not** mutate. Used
+     * by `commitAnalysis()` to invalidate prior memories, and by
+     * `previewRecoveryCycle()` to surface the same plan without applying
+     * it.
+     *
+     * A new memory supersedes an existing one when ALL of:
+     *   - existing.invalidatedAt is unset (still active);
+     *   - kinds match (defaulting to `'procedural'` when unset);
+     *   - `applicability` lists share at least one element;
+     *   - `|existing.confidence - new.confidence|` ≥ the policy's
+     *     `supersessionConfidenceDelta` (default 0.15).
+     *
+     * Each existing memory is claimed by at most one new memory per batch.
+     */
+    private computeSupersessions;
+    /**
+     * Compute confidence for a pattern cluster.
+     */
+    private computeConfidence;
+    /**
+     * Measure consistency of outcomes within a cluster.
+     */
+    private measureConsistency;
+    /**
+     * Extract a heuristic from a pattern cluster.
+     */
+    private extractHeuristic;
+    /**
+     * Extract a higher-level abstraction from a cluster.
+     */
+    private extractAbstraction;
+    /**
+     * Identify recurring patterns across trace clusters.
+     */
+    private identifyPatterns;
+    /**
+     * Measure cognitive drift: how much recent behavior deviates
+     * from stable patterns. Higher = more drift.
+     */
+    measureDrift(traces?: ExecutionTrace[]): number;
+    /**
+     * Produce a complete recovery health report.
+     *
+     * `memoryConsolidation` is computed against *active* memories only
+     * (those with no `invalidatedAt`). Counting superseded memories
+     * would inflate the ratio as the agent revises its beliefs, hiding
+     * that the live memory store has actually grown leaner.
+     */
+    assess(): RecoveryHealth;
+    recommend(): HealthRecommendation[];
+    /**
+     * Returns true if enough traces exist to justify a recovery cycle.
+     */
+    needsRecovery(): boolean;
+    private getUnprocessedTraces;
+    /**
+     * All memories ever consolidated by this Nidra instance, including
+     * those that have been invalidated by supersession. Use this for
+     * audit / replay; use `getActiveMemories()` for the "what's true now"
+     * view and `findMemories(query)` for richer queries.
+     */
+    getMemories(): readonly Readonly<ConsolidatedMemory>[];
+    /**
+     * The currently authoritative memories — those with no
+     * `invalidatedAt` set. This is the live view a consumer should
+     * inject into an agent or surface on a dashboard. Memories that
+     * have been superseded are excluded but remain in `getMemories()`
+     * for provenance.
+     */
+    getActiveMemories(): readonly Readonly<ConsolidatedMemory>[];
+    /**
+     * Bi-temporal / kind-aware query over the memory store: "what was
+     * true at any point in time".
+     *
+     * - `asOf` (ISO timestamp; default = now): include only memories
+     *   that were valid at that instant — `createdAt <= asOf` AND
+     *   (`invalidatedAt` is unset OR `invalidatedAt > asOf`). Set
+     *   `includeInvalidated` to `true` to drop the invalidation cutoff
+     *   and see every memory created on or before `asOf`.
+     * - `kind`: restrict to one or more memory kinds. Memories with no
+     *   explicit `kind` are treated as `'procedural'`.
+     * - `applicability`: exact match against any element of the
+     *   memory's `applicability` list.
+     * - `minConfidence`: drop memories below this confidence.
+     * - `limit`: cap the result length (no cap if undefined).
+     *
+     * Results are returned in insertion order (oldest first).
+     */
+    findMemories(query?: {
+        asOf?: string;
+        kind?: ConsolidatedMemoryKind | ConsolidatedMemoryKind[];
+        applicability?: string;
+        minConfidence?: number;
+        includeInvalidated?: boolean;
+        limit?: number;
+    }): ConsolidatedMemory[];
+    getTraces(): readonly Readonly<ExecutionTrace>[];
+    getCycleHistory(): readonly Readonly<RecoveryCycleResult>[];
+    exportState(): NidraStateSnapshot;
+    importState(snapshot: Partial<NidraStateSnapshot> | undefined): void;
+    getPolicy(): RecoveryPolicy;
+    updatePolicy(updates: Partial<RecoveryPolicy>): void;
+}
+//# sourceMappingURL=index.d.ts.map

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

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