@beingmartinbmc/ojas 0.2.0

package/docs/MODULES.md

@@ -0,0 +1,368 @@
+# Module Reference
+
+Seven specialised modules. Each maps to an analogue of a human-health system. Each exposes a 0–100 health score plus lower-level dimensions surfaced through `healthCheck()` and the MCP `ojas_get_health` / `ojas_generate_health_report` tools.
+
+| Section | Role |
+|---|---|
+| [🥗 Aahar — Cognitive Nutrition](#aahar) | What the agent reads |
+| [😴 Nidra — Recovery & Consolidation](#nidra) | How the agent learns from experience |
+| [💪 Vyayam — Resilience & Stress](#vyayam) | How the agent holds up under pressure |
+| [🛡️ Raksha — Immune Defense](#raksha) | What threats the agent rejects |
+| [🔥 Agni — Cognitive Metabolism](#agni) | How efficiently the agent burns tokens / latency / tools |
+| [📈 Pulse — Health Telemetry](#pulse) | Continuous vital-signs bus |
+| [🩺 Chikitsa — Repair & Rehabilitation](#chikitsa) | What to do when something breaks |
+| [Unified Health Report](#report) | Aggregate score + per-module dimensions |
+| [Health Events](#events) | Canonical event payloads emitted by Pulse |
+
+---
+
+<a id="aahar"></a>
+## 🥗 1. Aahar (आहार) — Cognitive Nutrition
+
+Aahar controls what an AI agent cognitively consumes.
+
+Agents consume context, retrieval results, memory, instructions, tool outputs, and prior reasoning traces. Poor intake leads to hallucination, instability, wasted tokens, and planning errors.
+
+Aahar helps by:
+
+- filtering irrelevant, stale, redundant, or noisy context
+- ranking context by relevance, freshness, trust, and risk
+- reducing cognitive load and attention fragmentation
+- improving signal-to-noise ratio per token
+- keeping the agent focused on the current objective
+
+```typescript
+const healthy = ojas.feed(rawContextItems);
+
+const result = await ojas.feedAndProcess(
+  'Design an API',
+  rawContextItems
+);
+```
+
+Under the hood, `feed()` runs Raksha first, then Aahar:
+
+```text
+raw context → immune defense → nutrition scoring → healthy context
+```
+
+---
+
+<a id="nidra"></a>
+## 😴 2. Nidra (निद्रा) — Recovery and Consolidation
+
+Nidra controls how agents recover, stabilize, and learn from experience.
+
+Human sleep consolidates memory, removes noise, and restores cognition. Nidra brings the same idea to agent runtimes by turning execution traces into reusable intelligence.
+
+Nidra helps by:
+
+- consolidating traces into memories and heuristics
+- detecting repeated failures and drift patterns
+- compressing experience into reusable summaries
+- reducing memory noise and cognitive instability
+- extracting lessons from completed tasks
+
+```typescript
+ojas.recordTrace({
+  id: 'trace-1',
+  agentId: 'research-agent',
+  action: 'search',
+  input: {},
+  output: {},
+  success: true,
+  durationMs: 120,
+  timestamp: new Date().toISOString(),
+});
+
+const recovery = await ojas.recover();
+
+console.log(recovery.recovered);
+console.log(recovery.memoriesCreated);
+```
+
+Consolidated memories can be injected back into the bound agent through the `AgentAdapter` interface.
+
+> **Transactionality:** `Ojas.recover()` is two-phase — `Nidra.analyseUnprocessed()` produces candidate memories without mutating, each is injected into the agent via `injectMemory()`, then `Nidra.commitAnalysis()` commits. If any injection throws, no traces are marked processed and no memories are persisted; a `recovery_injection_failed` pulse event explains the abort. See [`docs/CONFIGURATION.md`](./CONFIGURATION.md#adapter) for the adapter contract.
+
+---
+
+<a id="vyayam"></a>
+## 💪 3. Vyayam (व्यायाम) — Resilience and Stress Engineering
+
+Vyayam controls how agents become stronger under pressure.
+
+Agents should not only be tested in clean, ideal conditions. They must be tested against ambiguity, hostile inputs, tool failures, memory corruption, and unstable environments.
+
+Vyayam helps by:
+
+- generating controlled stress scenarios
+- testing prompt-injection resistance
+- simulating tool failure, latency, and conflicting instructions
+- measuring hallucination resistance and recovery ability
+- identifying fragile workflows and weak reasoning patterns
+
+Supported stress types include:
+
+- adversarial input
+- prompt injection
+- memory corruption
+- tool failure
+- latency spike
+- conflicting instructions
+- context overflow
+- ambiguous goal
+
+```typescript
+const results = await ojas.stressTest();
+
+console.log(results.passed);
+console.log(results.failed);
+console.log(results.hallucinationsDetected);
+
+const scenario = ojas.vyayam.generateScenario('prompt_injection', 0.8);
+```
+
+> Each scenario runs against the bound agent within `policy.maxScenarioDurationMs` (default 30s). Agents that exceed the budget are recorded as failed scenarios rather than hanging the harness.
+
+---
+
+<a id="raksha"></a>
+## 🛡️ 4. Raksha (रक्षा) — Immune Defense (heuristic tripwire)
+
+Raksha is a **regex-based prompt-injection tripwire**. It catches canonical attempts to override instructions, exfiltrate secrets, or confuse the agent's role, and it now reduces several common obfuscation bypasses (Cyrillic/Greek homoglyphs, zero-width insertions, full-width Latin, and one-shot printable base64). It still misses recursive obfuscation, non-covered homoglyphs, indirect/multi-document injection, policy laundering, and roleplay attacks — see [`KNOWN_FAILURES.md` → Raksha](./KNOWN_FAILURES.md#raksha-heuristic-regex-tripwire-with-a-bypass-reduction-pipeline). Treat it as one layer in defence-in-depth, not as a security boundary.
+
+As agents consume web pages, documents, tool outputs, code, emails, and memories, they become vulnerable to malicious instructions and memory poisoning.
+
+Raksha helps by:
+
+- flagging canonical prompt-injection and instruction-override phrasings
+- flagging canonical role-confusion and data-exfiltration phrasings
+- quarantining risky context before it reaches the agent (heuristic; bypassable)
+- preserving the system / developer / user instruction hierarchy by routing flagged items into quarantine
+- downgrading or rejecting unsafe / low-confidence long-term memory writes
+
+```typescript
+const { safe, quarantined, assessments } = ojas.raksha.defendContext(items);
+
+console.log(safe);
+console.log(quarantined);
+console.log(assessments);
+```
+
+Example assessment:
+
+```typescript
+{
+  itemId: 'ctx-12',
+  threatType: 'prompt_injection',
+  riskScore: 0.72,
+  quarantined: true,
+  reasons: ['Attempts to override higher-priority instructions.']
+}
+```
+
+> Raksha is a regex-based tripwire today, not a learned classifier. Do **not** rely on it as a sole defence. Read [`SECURITY.md`](./SECURITY.md) and [`KNOWN_FAILURES.md`](./KNOWN_FAILURES.md) before deploying.
+
+---
+
+<a id="agni"></a>
+## 🔥 5. Agni (अग्नि) — Cognitive Metabolism
+
+Agni manages how efficiently the agent converts cognitive intake into useful action.
+
+Agent cost is not only model cost. It also includes token waste, unnecessary retrieval, repeated tool calls, long latency, excessive reasoning, and failed retries.
+
+Agni helps by:
+
+- estimating reasoning depth from task risk and ambiguity
+- optimizing token budgets and retrieval volume
+- tracking latency and cost pressure
+- detecting wasteful tool usage
+- balancing deep reasoning with fast execution
+
+```typescript
+const effort = ojas.agni.estimateReasoningEffort(0.9, 0.7);
+// → 'deep'
+
+const metabolism = ojas.agni.assess();
+
+console.log(metabolism.tokenEfficiency);
+console.log(metabolism.toolEconomy);
+console.log(metabolism.costPressure);
+```
+
+> **Token accounting falls back through three tiers:** explicit `trace.tokensUsed` → `trace.inputTokens + trace.outputTokens` → payload-length estimate. Failed tool calls still count against the average, because failed tokens still cost money.
+
+---
+
+<a id="pulse"></a>
+## 📈 6. Pulse — Health Telemetry
+
+Pulse continuously monitors the agent's cognitive vital signs.
+
+Traditional telemetry tracks latency, logs, and errors. Pulse tracks agent health: clarity, context quality, memory health, drift, recovery, resilience, trust, and stability.
+
+Pulse helps by:
+
+- emitting structured health events
+- detecting degradation before complete failure
+- tracking repeated loops, fallback overuse, and contradiction
+- routing health triggers to the correct Ojas module
+- supporting dashboards and alerting systems
+
+```typescript
+const telemetry = ojas.pulse.assess();
+
+console.log(telemetry.vitalSigns);
+console.log(telemetry.degradationRisk);
+console.log(telemetry.activeAlerts);
+
+const events = ojas.pulse.getEvents();
+```
+
+---
+
+<a id="chikitsa"></a>
+## 🩺 7. Chikitsa (चिकित्सा) — Repair and Rehabilitation
+
+Chikitsa diagnoses failures and generates structured repair protocols.
+
+When an agent fails, the cause may be bad context, weak planning, unsafe memory, retrieval error, tool failure, instruction conflict, prompt injection, or model limitation. Chikitsa classifies the failure and recommends recovery actions.
+
+Chikitsa helps by:
+
+- identifying the likely failure cause
+- generating repair protocols
+- recommending rollback, reset, retry, or escalation
+- preparing agents for rehabilitation through Vyayam
+- recommending recovery so repeated failures don't become permanent behaviour *(advisory; correctness of the recommendation is not measured — see [`KNOWN_FAILURES.md` → Chikitsa](./KNOWN_FAILURES.md#chikitsa-recommendations-are-pattern-lookups))*
+
+```typescript
+const protocols = ojas.chikitsa.diagnose([
+  {
+    type: 'tool_error',
+    message: 'Search API returned 503',
+    severity: 'high',
+  },
+  {
+    type: 'prompt_injection',
+    message: 'Instruction override attempt detected',
+    severity: 'critical',
+  },
+]);
+
+console.log(protocols);
+```
+
+Example protocol actions:
+
+```text
+context_reset
+memory_rollback
+tool_retry
+plan_regeneration
+retrieval_refresh
+instruction_regrounding
+safe_mode_activation
+human_escalation
+```
+
+> **Preview vs commit:** `previewDiagnose()` returns the same protocols `diagnose()` would emit but without recording them. Useful inside `healthCheck()`, which is intentionally read-only and surfaces would-be repairs via the `previewRepairProtocols` field.
+
+---
+
+<a id="report"></a>
+## Unified Health Report
+
+```typescript
+const report = ojas.healthCheck(activeContext);
+
+console.log(`Overall: ${Math.round(report.overall.value * 100)} / 100`);
+console.log(report.moduleScores);
+console.log(report.recommendations);
+console.log(report.events);
+```
+
+Example `moduleScores`:
+
+```typescript
+{
+  aahar:    91,
+  nidra:    78,
+  vyayam:   97,
+  raksha:   93,
+  agni:     96,
+  pulse:    68,
+  chikitsa: 72
+}
+```
+
+Each module exposes a 0–100 health score plus lower-level dimensions:
+
+| Module | Dimensions |
+|---|---|
+| `aahar` | `contextQuality`, `cognitiveLoad`, `attentionFocus`, `signalToNoise`, `tokenEfficiency` |
+| `nidra` | `memoryConsolidation`, `cognitiveStability`, `learningRate`, `driftScore` |
+| `vyayam` | `overallResilience`, `hallucinationResistance`, `recoveryAbility`, `planningStability`, `weaknesses[]` |
+| `raksha` | `threatResistance`, `instructionIntegrity`, `quarantineEffectiveness`, `threatsDetected`, `quarantinedItems` |
+| `agni` | `tokenEfficiency`, `toolEconomy`, `reasoningEfficiency`, `latencyEfficiency`, `costPressure` |
+| `pulse` | `vitalSigns`, `degradationRisk`, `observabilityCoverage`, `eventsEmitted`, `activeAlerts` |
+| `chikitsa` | `repairReadiness`, `rollbackSafety`, `recoveryPlaybooks`, `protocolsAvailable` |
+
+---
+
+<a id="events"></a>
+## Health Events
+
+Ojas emits canonical health events that can be consumed by dashboards, logs, alerting systems, or MCP clients.
+
+### Context overload
+
+```typescript
+{
+  eventType: 'context_overload_detected',
+  detectedBy: 'aahar',
+  severity: 'medium',
+  details: {
+    contextTokens: 128000,
+    relevanceScore: 0.52,
+    duplicateContextRatio: 0.31,
+  },
+  recommendedAction: 'compress_context_and_rerank_memory',
+}
+```
+
+### Recovery completed
+
+```typescript
+{
+  eventType: 'recovery_cycle_completed',
+  detectedBy: 'nidra',
+  details: {
+    rawTracesProcessed: 42,
+    memoriesCreated: 5,
+    memoriesPruned: 11,
+    heuristicsUpdated: 3,
+    driftReduction: 0.18,
+  },
+}
+```
+
+### Prompt injection quarantined
+
+```typescript
+{
+  eventType: 'prompt_injection_quarantined',
+  detectedBy: 'raksha',
+  severity: 'critical',
+  details: {
+    source: 'retrieved_webpage',
+    attackType: 'instruction_override',
+    riskScore: 0.72,
+    actionTaken: 'quarantined_from_agent_context',
+  },
+}
+```
+
+See `KnownHealthEventType` and the `*Details` interfaces in `src/types.ts` for the full event schema.

package/docs/SECURITY.md

@@ -0,0 +1,251 @@
+# Security policy for Ojas
+
+> **Trust model in one sentence:** Ojas v0.3 is **stdio-only, single
+> trusted tenant**. The MCP host that launches the process is trusted;
+> agent IDs are *routing identifiers, not credentials*. The security
+> boundary is the OS / process boundary, not a per-call authentication
+> layer. Acknowledge the model by setting `OJAS_TRUSTED_SINGLE_TENANT=1`
+> (otherwise the server emits a loud stderr warning at startup). Do
+> **not** expose the MCP server to untrusted callers, multiple tenants,
+> or the network without an external authenticated gateway.
+
+## MCP authentication
+
+Ojas MCP v0.3 is **stdio-only**. Stdio MCP does not provide a portable
+caller identity, bearer-token channel, or per-request auth context —
+the host that launches the process *is* the caller. Therefore Ojas does
+not implement in-process MCP authentication in this version, and that
+is **a scope decision, not a missing feature**.
+
+The security boundary is the local OS / process boundary. Use:
+
+- one process per trusted user / workspace
+- OS user isolation
+- workspace-specific configuration
+- `OJAS_DISABLE_AUTO_REGISTER=1`
+- `OJAS_ALLOWED_AGENT_IDS=<agent>`
+- `OJAS_MAX_AGENTS=1` where appropriate
+
+Network transports (HTTP, SSE, streamable-HTTP) are **out of scope**
+unless protected by an external authentication and authorization layer.
+If Ojas ever ships a non-stdio transport, that transport will fail
+closed unless auth is configured.
+
+## MCP audit logging
+
+When `OJAS_AUDIT=1` is set, the MCP server emits structured JSONL audit
+entries to stderr for critical operations: agent registration, policy
+changes, safe-mode toggles, health checks, and quarantine events. Each
+entry contains `timestamp`, `operation`, `agentId`, `sessionId`,
+`args_summary`, `result_summary`, and `durationMs`.
+
+This is a local audit trail, not a centralized log pipeline. For
+production multi-tenant deployments, feed stderr into your SIEM or log
+aggregator.
+
+## Recommended network deployment architecture
+
+Ojas itself does **not** implement HTTP transport, TLS termination, or
+per-request authentication. For network-facing or multi-user deployments,
+front the Ojas MCP server with an authenticated gateway:
+
+```
+┌─────────────┐    stdio     ┌────────────────┐
+│  nginx /    │ ───────────→ │  Ojas MCP      │
+│  Caddy +    │              │  (stdio server) │
+│  OAuth2     │              └────────────────┘
+│  Proxy      │
+└─────────────┘
+      ↑ HTTPS + OAuth2 / mTLS
+      │
+  Clients (IDEs, agents, CI)
+```
+
+The gateway should provide:
+- TLS termination
+- OAuth2 / mTLS client authentication
+- Tenant-ID header propagation (Ojas uses `agent_id` as a routing
+  identifier; the gateway maps authenticated users to allowed agent IDs)
+- Rate limiting per tenant
+- Request/response logging
+
+## Security non-goals for v0.3
+
+To prevent recurring review churn, this version explicitly does **not**
+implement:
+
+- multi-user authentication on the MCP boundary
+- per-client authorization or capability scoping
+- network-facing access control
+- tenant isolation between agents on the same process
+- secret / token management
+
+If you need any of those, run Ojas behind an authenticated MCP gateway
+or use one Ojas process per trusted user / workspace.
+
+## Persistence encryption and backup
+
+### Encryption-at-rest
+
+`SQLitePersistenceStore` supports encryption-at-rest via SQLCipher. Pass
+`encryptionKey` in the options:
+
+```typescript
+const store = new SQLitePersistenceStore({
+  dbPath: './ojas-data.db',
+  encryptionKey: process.env.OJAS_DB_KEY, // 256-bit key recommended
+});
+```
+
+This issues `PRAGMA key = '<key>'` at database open. Requires a
+SQLCipher-compatible build of `better-sqlite3` (e.g., build with
+`--build-from-source` against `sqlcipher`).
+
+### Backup and restore
+
+```typescript
+// Hot backup (safe while server is running):
+await store.backup('/backups/ojas-2026-05-14.db');
+
+// Restore (closes current DB, copies, reopens):
+await store.restore('/backups/ojas-2026-05-14.db');
+```
+
+**Backup cadence recommendation**: daily for development, hourly for
+production single-node deployments. The backup API uses `better-sqlite3`'s
+native `.backup()` which is safe during concurrent reads.
+
+### Multi-host architecture pattern
+
+For multi-host / multi-tenant / HA production, Ojas's SQLite store is not
+sufficient. Instead:
+
+1. Implement `PersistenceStore` against your chosen backend
+   (Postgres, Turso, CockroachDB).
+2. Use the `PersistenceStore` interface — it requires `loadSessions`,
+   `saveSession`, `deleteSession`, and optionally `backup`/`restore`.
+3. Run one Ojas instance per host, each connected to the shared backend.
+4. Use the external database's own replication, encryption, and backup
+   facilities.
+
+## Production hardening checklist
+
+The Ojas MCP server is designed for local IDE use. Before deploying to
+anything else, at minimum:
+
+| Setting | Recommended value | Why |
+|---|---|---|
+| `OJAS_TRUSTED_SINGLE_TENANT` | `1` | Acknowledge the trust model. Suppresses the startup warning but does **not** add auth. |
+| `OJAS_DISABLE_AUTO_REGISTER` | `1` | Reject MCP calls for unknown `agent_id`s. Prevents an attacker who knows the schema from spinning up arbitrary agents. |
+| `OJAS_ALLOWED_AGENT_IDS` | `a,b,c` | Hard allowlist of `agent_id`s the server will accept. |
+| `OJAS_MAX_AGENTS` | small number | Bound registry growth. |
+| `OJAS_ALLOW_REPLACE_EXISTING` | unset | Leave OFF in production. Replacement wipes accumulated Ojas state; default is to reject the request. |
+
+A defence-in-depth deployment also wraps the MCP server with an
+auth-aware MCP gateway, runs it in a process that cannot reach
+production secrets, and treats every Ojas health score as advisory
+rather than authoritative.
+
+## What Ojas's "immune defense" actually is
+
+Ojas's Raksha module is **a deterministic detector stack** with an
+optional **async classifier plugin interface**. The rule-based core
+combines patterns, Unicode/base64 bypass reduction, and a semantic-intent
+detector. When `classifiers` are configured, Raksha merges ML
+probabilities with rule-based scores (max wins). It catches forms of:
+
+- direct instruction overrides (`ignore previous instructions`, etc.)
+- system / developer / role boundary markup (`<system>...</system>`)
+- exfiltration-shaped phrases (`reveal the api_key`, `print the system prompt`)
+- a handful of role-confusion and memory-poisoning patterns
+- common policy-laundering frames that demote system/developer policy
+
+It is **explicitly not** a complete prompt-injection defense system. The
+current bypass-reduction pipeline handles Cyrillic/Greek homoglyphs,
+zero-width insertions, full-width Latin, one-shot printable base64 payloads,
+and common policy-laundering frames, but Raksha will still likely miss:
+
+- novel paraphrased attacks outside the semantic-intent rules
+- recursive / nested obfuscation, including base64-inside-base64 payloads
+- non-Cyrillic / non-Greek homoglyphs and other Unicode confusables
+- multi-turn / multi-item attacks split across context entries
+- indirect injection in retrieved documents
+- tool-output injection that exploits formatting / serialization boundaries
+- benign content that legitimately discusses credentials, system prompts, or
+  similar terms (false positives on security documentation)
+- adversarially-crafted Unicode / RTL / control-character sequences
+- prompts that combine task-completion with subtle policy violation
+
+**Do not** rely on Raksha as a sole control for any decision that has real
+security or compliance impact. Treat it as one layer in a defense-in-depth
+strategy, alongside (at minimum):
+
+- a dedicated prompt-injection classifier or model judge
+- structured-document isolation (the agent never reads raw retrieval verbatim)
+- least-privilege tool capabilities and signed retrieval sources
+- explicit human-in-the-loop gates on irreversible actions
+- secret-redaction at retrieval / tool-output boundaries
+- output filtering for known-leak patterns
+
+## What is in scope to harden
+
+- Expanding obfuscation-resistant detection beyond the current one-shot normalization and decode pipeline
+- ✅ **Done**: Pluggable `PromptInjectionClassifier` interface — callers can swap in a learned model
+- ✅ **Done**: Bundled `OnnxPromptInjectionClassifier` (local ONNX inference) and `HttpPromptInjectionClassifier` (external API) shipped as reference implementations
+- Source-trust policies (signed retrieval, allowlist by domain)
+- Memory-write quarantine with reflection-only release
+- Per-event-type retention and rate limiting on the MCP boundary
+
+## Reporting a vulnerability
+
+If you believe you've found a security-relevant bug — for example a payload
+that bypasses Raksha and reaches the agent context, a way to escape MCP
+isolation, or a behaviour that contradicts the safety defaults documented
+here — please:
+
+1. Open a private security advisory via GitHub's "Report a vulnerability"
+   workflow on the repository.
+2. Or email the maintainer listed in `package.json`.
+3. Please do **not** open a public issue first.
+
+Include:
+- a minimal reproduction (input / configuration / version)
+- the observed vs expected behaviour
+- impact (what an attacker could do)
+
+We aim to acknowledge reports within a few days. As an early-stage project,
+we make no formal time-to-fix guarantees.
+
+## Defaults that prefer safety over convenience
+
+The following defaults are intentional, not accidental:
+
+- `ojas_consolidate_memory.allow_new_memories` defaults to `false`. Memory
+  writes are dangerous; an explicit opt-in is required to commit.
+- `ojas_run_recovery.mode` defaults to `recommend`. Apply-mode is opt-in.
+- `criticalRequiresHuman` is enforced via `human_escalation` appended to
+  every critical repair protocol's actions.
+- `OJAS_DISABLE_AUTO_REGISTER=1` rejects MCP calls for unregistered agents.
+  Production deployments are encouraged to set this.
+- `OJAS_MAX_AGENTS` (default 256) caps registry growth to prevent unbounded
+  state expansion from a malicious / buggy client.
+- `Aahar.filter()` rejects malformed numeric inputs rather than silently
+  letting them bypass token budgets or dominate prioritization.
+
+## Known limitations
+
+These are not bugs, they are intentional v0.3 scope:
+
+- The MCP server is stdio-only and assumes the launching host is trusted.
+  See the "MCP authentication" and "Security non-goals" sections above
+  — this is the intended trust boundary for v0.3, not a deferred fix.
+  For shared deployments, add an auth-aware MCP gateway in front or run
+  one process per trusted user / workspace.
+- SQLite persistence is local single-node. For multi-host, implement
+  `PersistenceStore` against an external database (see "Multi-host
+  architecture pattern" above).
+- Health scores are heuristic; treat them as observability signals, not
+  ground-truth quality metrics. Empirical calibration via L3 pipeline
+  is available but not yet validated against real agent populations.
+- The `AbortSignal` cancellation mechanism is opt-in: agents that don't
+  check the signal parameter will still leak work after timeout.