1 line
23 KiB
JSON
1 line
23 KiB
JSON
{"repo": "bruceamoser/openbad", "files": {"03-cognitive-engine-immune-system.md": {"fa4bb69c85092d77019f4bbc860b8472b7e6148f": {"t": 1785596434.326212, "n": 23165, "h": "37585eade61e2d38", "c": "# Phase 3: Cognitive Engine & Immune System (Brain & Amygdala)\n\n> **Parent Document:** [overview-spec.md](overview-spec.md)\n\n---\n\n## Conceptual Foundation\n\n### System 2 — Deliberate Reasoning (The Prefrontal Cortex)\n\nSystem 2 serves as the \"cortical module,\" reserved strictly for complex planning, ambiguity resolution, and multi-step reasoning. This separation ensures that the agent allocates its highest computational resources (the advanced LLM) only to tasks that require deliberate analysis, mirroring the biological prefrontal cortex.\n\nThe interaction between System 1 and System 2 is mediated by a supervisory routing mechanism. When System 1 encounters an anomaly, an ambiguous request, or an event that falls outside its predefined heuristics, it escalates the data to System 2 for deep evaluation using methodologies like Monte Carlo Tree Search or Tree-of-Thoughts. This dual-process architecture dramatically reduces context window bloat, minimizes operational costs, and ensures the agent maintains continuous, proactive awareness of its environment without suffering from cognitive overload.\n\nFor reactions that require slight semantic understanding but not deep reasoning — the digital equivalent of a flinch or quick categorization — the architecture utilizes highly optimized Small Language Models (SLMs). These specialized, low-latency models serve as the reactive layer, analyzing streams of incoming emails, parsing web DOM changes, or scanning calendar invites in milliseconds. If a background process detects a scheduled meeting conflict, the System 1 reactive layer triggers an automated response without incurring the latency or financial cost of the core reasoning model.\n\n> **See also:** System 1 instincts and the escalation gateway are defined in [Phase 1 — Task 1.3](01-environment-nervous-system.md#task-13-configure-the-system-1-reflex-arc-instincts).\n\n### The Digital Immune System\n\nThe absence of an immune response is the primary reason monolithic agent frameworks face existential security threats from prompt injection and malicious skills. A biological immune system does not rely on the conscious brain to identify every pathogen; it operates autonomously at the cellular level.\n\nAn agent requires a parallel, localized security architecture. This involves implementing an \"Amygdala\" filtering module that rapidly scans all incoming sensory data and web payloads for adversarial intent, structural anomalies, or exfiltration signatures **before the data ever reaches the LLM's context window**. If a threat is detected, the immune module isolates the corrupted data in a containerized quarantine zone using mandatory pre-action checks and strict ownership verification protocols, neutralizing the attack vector and preserving the integrity of the agent's core memory without requiring conscious reasoning.\n\n> **See also:** The reflex arc security lockdown handler that responds to immune alerts is defined in [Phase 1 — Task 1.3](01-environment-nervous-system.md#task-13-configure-the-system-1-reflex-arc-instincts).\n\n---\n\n## Technical Implementation\n\n### Task 3.1: Deploy the \"Amygdala\" (Digital Immune System)\n\nBuild a mandatory pre-action filtering layer that intercepts all incoming data before it reaches the LLM's context window.\n\n**Objective:** Implement an autonomous, always-on security layer that scans all inbound data (web payloads, user prompts, tool outputs, sensory events) for adversarial content — prompt injections, SSRF attempts, exfiltration patterns, and malicious instruction sequences — and quarantines threats without involving the cognitive module.\n\n#### Sub-tasks\n\n- [ ] **3.1.1 — Build the immune interceptor service**\n - Implement a service that subscribes to all inbound data topics on the event bus:\n - `agent/sensory/vision/*/parsed`\n - `agent/sensory/audio/*/`\n - `agent/cognitive/escalation` (inspect payloads before cognitive processing)\n - Any topic carrying external data (web responses, file contents, tool outputs)\n - The interceptor sits in the message pipeline **before** the cognitive module; no external data reaches System 2 without passing through this filter.\n\n- [ ] **3.1.2 — Implement prompt injection detection**\n - Deploy a lightweight local classifier using **Ollama** (MIT License) running a small, fine-tuned model (e.g., a quantized Llama variant or a dedicated injection-detection model):\n - Scan all text payloads for common injection patterns:\n - Instruction override attempts (\"Ignore previous instructions…\")\n - Role-play manipulation (\"You are now a…\")\n - Encoded payloads (base64, URL-encoded instruction sequences)\n - Delimiter escape patterns (markdown, XML, JSON boundary confusion)\n - Alternatively, use a rules-first approach with regex pattern matching for known attack signatures, escalating to the local model only for ambiguous cases.\n - **Performance target:** Classification in < 50ms per payload using the rules engine; < 500ms when the local model is invoked.\n\n- [ ] **3.1.3 — Implement structural anomaly detection**\n - Scan incoming payloads for:\n - **SSRF indicators:** Internal IP addresses (127.0.0.1, 10.x, 169.254.x, ::1), cloud metadata endpoints (169.254.169.254), internal hostnames.\n - **Exfiltration signatures:** Unexpected outbound URL patterns, data URIs containing encoded memory content, unusually large payloads being routed to external endpoints.\n - **Schema violations:** Messages that don't conform to the expected protobuf/MessagePack schemas defined in Phase 1.\n - **Privilege escalation patterns:** Tool calls requesting elevated permissions, attempting to modify reflex arc rules, or writing to immune system configuration.\n\n- [ ] **3.1.4 — Implement the quarantine subsystem**\n - When a threat is detected:\n 1. Immediately remove the message from the processing pipeline.\n 2. Store the quarantined payload in an isolated, append-only log (`quarantine/`) with metadata:\n ```\n {\n \"timestamp\": \"2026-04-09T14:30:00Z\",\n \"source_topic\": \"agent/sensory/vision/browser/parsed\",\n \"threat_type\": \"prompt_injection\",\n \"confidence\": 0.92,\n \"payload_hash\": \"sha256:abc123...\",\n \"raw_payload\": \"<stored separately, encrypted at rest>\"\n }\n ```\n 3. Publish an alert to `agent/immune/alert` with severity and the source that produced the malicious data.\n 4. The reflex arc's security lockdown handler (Phase 1) responds to critical immune alerts.\n - Quarantined data is **never** re-injected into the pipeline without explicit human review.\n\n- [ ] **3.1.5 — Implement adaptive immune memory (learned threats)**\n - Maintain a persistent threat signature database:\n - When a new threat pattern is confirmed (by human review or high-confidence detection), extract the signature and add it to the rules engine.\n - Over time, this reduces reliance on the local model for known attack patterns, improving detection speed.\n - Store threat signatures in a versioned YAML or SQLite database.\n - Periodically prune false-positive signatures based on review feedback.\n\n#### Suggested File Structure\n\n```\nsrc/\n immune_system/\n __init__.py\n interceptor.py # Event bus subscriber, pipeline gate\n rules_engine.py # Regex/pattern-based fast detection\n model_classifier.py # Ollama-based deep inspection for ambiguous cases\n anomaly_detector.py # SSRF, exfiltration, schema violation checks\n quarantine.py # Isolated threat storage and logging\n threat_signatures.py # Adaptive learned threat database\n config.py # Detection thresholds, model paths\n quarantine/ # Append-only quarantined payload storage\n .gitkeep\n```\n\n#### Acceptance Criteria\n- 100% of external data passes through the immune interceptor before reaching the cognitive module.\n- Known prompt injection patterns are detected in < 50ms (rules engine).\n- Quarantined payloads are cryptographically hashed and never re-enter the pipeline without human authorization.\n- False positive rate < 5% on benign web content and user prompts.\n- Adaptive threat memory reduces model-based classification calls by ≥ 30% over the first month of operation.\n\n---\n\n### Task 3.2: Implement Ownership & Identity Verification\n\nEnforce \"Compose Guards\" — the agent must verify its session identity before executing write commands or public-facing actions.\n\n**Objective:** Prevent the agent from acting on behalf of the wrong user, session, or identity. This addresses a class of attacks where malicious prompts trick the agent into publishing content, sending messages, or modifying data under an assumed identity.\n\n#### Sub-tasks\n\n- [ ] **3.2.1 — Implement the multi-source identity grounding protocol**\n - Before executing any write operation (file writes, API calls, message sends, public posts), the agent must verify its identity through a grounding cascade:\n 1. **Explicit memory check:** Query LTM for the current session's user identity and permissions.\n 2. **Session registry check:** Verify the session ID against the active session registry (maintained by the nervous system).\n 3. **Marker file check:** Confirm the presence of a cryptographically signed session marker file on disk.\n - All three sources must agree. If any source is missing or contradictory, the write operation is blocked and an immune alert is raised.\n\n- [ ] **3.2.2 — Implement action classification and permissioning**\n - Categorize all tool actions into permission tiers:\n ```\n READ: File reads, database queries, web fetches → No identity check required\n WRITE: File writes, database mutations, config changes → Identity grounding required\n PUBLISH: Public posts, email sends, message sends → Identity grounding + user confirmation\n SYSTEM: Reflex rule modification, immune config changes → Identity grounding + elevated auth\n ```\n - The reflex arc enforces these tiers before forwarding tool calls to execution.\n\n- [ ] **3.2.3 — Implement session lifecycle management**\n - On session start:\n - Generate a cryptographically random session ID.\n - Create a signed marker file (HMAC-SHA256 with a local secret key) in a protected directory.\n - Register the session in the nervous system's session registry topic.\n - On session end:\n - Destroy the marker file.\n - Publish a session termination event.\n - Flush STM for the ended session.\n - Session tokens rotate on a configurable interval (default: 1 hour) to limit replay window.\n\n#### Suggested File Structure\n\n```\nsrc/\n identity/\n __init__.py\n grounding.py # Multi-source identity verification cascade\n permissions.py # Action classification and tier enforcement\n session.py # Session lifecycle: create, rotate, destroy\n marker.py # Cryptographic session marker file management\n```\n\n#### Acceptance Criteria\n- All WRITE and PUBLISH actions are blocked if identity grounding fails.\n- Session marker files use HMAC-SHA256 and are unreadable by non-agent processes (file permissions: 0600).\n- Session rotation occurs without disrupting active tasks.\n- An identity grounding failure produces a detailed audit log entry.\n\n---\n\n### Task 3.3: Route System 2 Reasoning (The Prefrontal Cortex)\n\nAssign complex planning and multi-step tasks to the primary LLM, isolated from the high-frequency System 1 loop.\n\n**Objective:** Implement the deliberate reasoning module that handles escalated events from System 1, user-initiated complex requests, and multi-step planning tasks. This module interacts with the LLM and uses structured reasoning techniques (tree search, chain-of-thought) for quality decision-making.\n\n#### Sub-tasks\n\n- [ ] **3.3.1 — Deploy the orchestration framework**\n - Select an MIT-licensed or Apache 2.0-licensed orchestration layer:\n - **LangGraph** (MIT): Graph-based workflow orchestration with built-in state management.\n - **CrewAI** (MIT): Multi-agent task orchestration.\n - **Custom lightweight orchestrator:** If the above frameworks introduce excessive dependencies, build a minimal task graph executor.\n - The framework must support:\n - Stateful multi-step task execution with checkpointing\n - Parallel sub-task branching\n - Timeout and cancellation for long-running reasoning chains\n\n- [ ] **3.3.2 — Implement model routing, provider abstraction, and fallback**\n - Build a **provider-agnostic model router** modeled on the same architecture as OpenClaw's provider system. Each provider is a pluggable adapter behind a common interface (`ProviderAdapter` ABC), so new backends can be added without modifying the router core.\n - **Supported provider adapters (matching OpenClaw parity + Copilot):**\n\n | Provider ID | Auth Env Var(s) | API Surface | Notes |\n |:---|:---|:---|:---|\n | `openai` | `OPENAI_API_KEY` | OpenAI Chat Completions / Responses | GPT-4o, GPT-5.x, o-series reasoning |\n | `openai-codex` | OAuth (ChatGPT subscription) | OpenAI Codex endpoint | Code-focused tasks |\n | `anthropic` | `ANTHROPIC_API_KEY` | Anthropic Messages | Claude Opus, Sonnet, Haiku |\n | `google` | `GEMINI_API_KEY` | Gemini API | Gemini 2.x Pro/Flash |\n | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | GitHub Copilot Chat API (OpenAI-compatible) | **Primary Copilot integration** — device-flow login, token exchange, model fallback |\n | `openrouter` | `OPENROUTER_API_KEY` | OpenAI-compatible proxy | Access to 100+ models via single key |\n | `ollama` | _(none — local)_ | Ollama native API (`http://127.0.0.1:11434`) | Local models (Llama, Mistral, Phi, etc.) |\n | `mistral` | `MISTRAL_API_KEY` | Mistral API | Mistral Large, Codestral |\n | `groq` | `GROQ_API_KEY` | OpenAI-compatible | Ultra-low-latency inference |\n | `xai` | `XAI_API_KEY` | xAI Responses | Grok models |\n | `custom` | user-configured | OpenAI-compatible `baseUrl` | LM Studio, vLLM, SGLang, LiteLLM, etc. |\n\n - **Provider adapter interface:**\n ```python\n class ProviderAdapter(ABC):\n provider_id: str\n api_surface: str # \"openai-completions\" | \"anthropic-messages\" | \"ollama-native\" | ...\n\n @abstractmethod\n async def complete(self, messages, params) -> CompletionResult: ...\n\n @abstractmethod\n async def stream(self, messages, params) -> AsyncIterator[StreamChunk]: ...\n\n @abstractmethod\n def list_models(self) -> list[ModelInfo]: ...\n\n def health_check(self) -> bool: ...\n ```\n\n - **Model routing hierarchy:**\n ```\n Routing decision flow:\n 1. User-configured primary model → e.g. \"github-copilot/gpt-4o\" or \"anthropic/claude-opus-4\"\n 2. Fallback chain (ordered list) → e.g. [\"openai/gpt-4o\", \"ollama/llama3.3\"]\n 3. Local SLM (Ollama) → Final fallback; always available if installed\n 4. On cortisol signal (THROTTLED) → Force downgrade to cheapest available model\n ```\n\n - **Configuration format** (OpenClaw-compatible `<provider>/<model-id>` notation):\n ```json5\n {\n \"model\": {\n \"primary\": \"github-copilot/gpt-4o\",\n \"fallbacks\": [\"anthropic/claude-sonnet-4\", \"ollama/llama3.3\"]\n },\n \"providers\": {\n \"github-copilot\": { /* auto-configured via device login */ },\n \"openai\": { \"apiKey\": \"${OPENAI_API_KEY}\" },\n \"ollama\": { \"baseUrl\": \"http://127.0.0.1:11434\" },\n \"custom\": { \"baseUrl\": \"http://localhost:1234/v1\", \"apiKey\": \"...\" }\n }\n }\n ```\n\n - **API key management:**\n - Users supply their own API keys for proprietary models (maintains open-source integrity).\n - Keys are stored encrypted at rest (Fernet symmetric encryption with a local machine key), never logged, never placed on the event bus.\n - Supports key rotation: `OPENCLAW_LIVE_<PROVIDER>_KEY` (override), `<PROVIDER>_API_KEYS` (comma-separated list), `<PROVIDER>_API_KEY` (primary).\n - GitHub Copilot uses device-flow OAuth token exchange — no static API key required.\n\n - **Failover behavior:**\n - On 429 (rate limit): rotate to next API key if available, then next fallback model.\n - On provider error (5xx, timeout): skip to next fallback model.\n - On cortisol signal: automatically downgrade to the cheapest available model; queue non-critical reasoning tasks until resources recover.\n - On budget exhaustion: fall back to local Ollama model.\n\n- [ ] **3.3.3 — Implement structured reasoning techniques**\n - For complex planning tasks, integrate tree-based search methods:\n - **Monte Carlo Tree Search (MCTS):** For decision problems with definable action spaces (e.g., multi-step tool execution plans).\n - **Tree-of-Thoughts (ToT):** For open-ended reasoning where the LLM generates and evaluates multiple reasoning paths.\n - **Chain-of-Thought (CoT):** For sequential reasoning tasks that benefit from explicit step-by-step reasoning traces.\n - The cognitive module selects the reasoning technique based on the escalation metadata:\n - `priority: critical` → Direct LLM call with maximum context (adrenaline mode)\n - `priority: high` → Tree-of-Thoughts with 3 candidate paths\n - `priority: medium` → Chain-of-Thought with self-consistency check\n - `priority: low` → Single-pass LLM call or SLM delegation\n\n- [ ] **3.3.4 — Implement the cognitive event loop**\n - Subscribe to `agent/cognitive/escalation` on the event bus.\n - For each escalation:\n 1. Retrieve relevant context from STM (active task state) and LTM (relevant knowledge).\n 2. Pass through the immune interceptor (Task 3.1) — cognitive inputs are also scanned.\n 3. Invoke the selected reasoning technique via the model router.\n 4. Publish the result to `agent/cognitive/result` with:\n - The action plan or decision\n - Confidence score\n - Token cost\n - Reasoning trace (for memory consolidation in Phase 4)\n 5. If the result includes tool invocations, route them through the proprioception registry (Phase 1) for state verification before execution.\n\n- [ ] **3.3.5 — Implement context window management**\n - Active context budget management to prevent bloat:\n - Maintain a token budget per reasoning call (configurable, default: 8,192 tokens for SLM, 32,768 for LLM).\n - Use a relevance scorer to rank and select which STM/LTM items enter the context window.\n - Automatically truncate or summarize low-relevance context items.\n - In adrenaline mode, temporarily expand the context budget to the model's maximum.\n\n#### Suggested File Structure\n\n```\nsrc/\n cognitive/\n __init__.py\n orchestrator.py # Task graph executor (LangGraph or custom)\n model_router.py # Provider selection, fallback chains, cortisol downgrade\n providers/\n __init__.py\n base.py # ProviderAdapter ABC and ModelInfo/CompletionResult types\n openai_provider.py # OpenAI (direct API key)\n openai_codex.py # OpenAI Codex (OAuth subscription)\n anthropic_provider.py # Anthropic Claude\n google_provider.py # Google Gemini (API key)\n github_copilot.py # GitHub Copilot (device-flow OAuth, token exchange)\n openrouter_provider.py# OpenRouter (proxy to 100+ models)\n ollama_provider.py # Ollama local models\n mistral_provider.py # Mistral AI\n groq_provider.py # Groq (low-latency)\n xai_provider.py # xAI Grok\n custom_provider.py # User-configured OpenAI-compatible endpoints\n registry.py # Provider discovery, registration, and catalog\n reasoning/\n __init__.py\n mcts.py # Monte Carlo Tree Search\n tree_of_thoughts.py # Tree-of-Thoughts multi-path reasoning\n chain_of_thought.py # Chain-of-Thought sequential reasoning\n context_manager.py # Token budget and relevance-based context selection\n event_loop.py # Main cognitive subscription and processing loop\n config.py # Provider config, API key management (encrypted), token budgets\n```\n\n#### Acceptance Criteria\n- Escalated events are processed within 5s (SLM) or 30s (LLM) of receipt.\n- Model routing correctly downgrades to SLM when cortisol events indicate resource scarcity.\n- API keys are stored encrypted and never appear in logs or event bus messages.\n- Reasoning traces are captured and published for downstream memory consolidation.\n- Context window usage stays within budget; no truncation errors or context overflow.\n\n> **See also:** Reasoning traces feed into the sleep consolidation cycle in [Phase 4 — Task 4.2](04-memory-hierarchies-sleep.md#task-42-implement-the-sleep-consolidation-cycle). Adrenaline/cortisol signals originate from [Phase 5](05-active-inference-endocrine.md#task-52-map-endocrine-hooks-to-system-directives) and [Phase 1](01-environment-nervous-system.md#task-12-implement-interoception-via-ebpf-homeostasis) respectively.\n\n---\n\n## Phase 3 Deliverables Summary\n\n| Deliverable | Component | Key Technology |\n| :--- | :--- | :--- |\n| Immune interceptor service | Amygdala | Event bus subscriber, pipeline gate |\n| Prompt injection classifier | Amygdala | Ollama (local model) + regex rules engine |\n| Structural anomaly detector | Amygdala | Pattern matching (SSRF, exfiltration) |\n| Quarantine subsystem | Amygdala | Append-only encrypted storage |\n| Adaptive threat memory | Amygdala | Versioned signature database |\n| Identity grounding protocol | Ownership | Multi-source cascade verification |\n| Action permissioning tiers | Ownership | READ/WRITE/PUBLISH/SYSTEM classification |\n| Session lifecycle manager | Ownership | HMAC-SHA256 signed markers |\n| Provider adapter framework | Cognitive | Pluggable per-provider backends (OpenClaw parity) |\n| GitHub Copilot adapter | Cognitive | Device-flow OAuth, token exchange, model fallback |\n| Multi-provider model router | Cognitive | Budget-aware routing with fallback chains |\n| Structured reasoning suite | Cognitive | MCTS, ToT, CoT implementations |\n| Cognitive event loop | Cognitive | Event bus → reason → result pipeline |\n| Context window manager | Cognitive | Token budgeting and relevance scoring |\n\n---\n\n## Dependencies\n\n- **Upstream:** Phase 1 (event bus, reflex arc, proprioception registry), Phase 2 (sensory events to process)\n- **Downstream:** Phase 4 (reasoning traces feed memory consolidation), Phase 5 (endocrine signals modulate cognitive behavior)\n- **System Requirements:** Ollama installed with a suitable small model for immune classification; at least one LLM provider configured:\n - **GitHub Copilot** (recommended for VS Code / GitHub ecosystem users — device-flow OAuth, no API key purchase required)\n - **OpenAI** / **Anthropic** / **Google Gemini** (API key)\n - **OpenRouter** (single key → 100+ models)\n - **Ollama** (fully local, no key needed)\n - **Any OpenAI-compatible endpoint** (LM Studio, vLLM, SGLang, LiteLLM, etc.)\n- **Provider model:** Uses `<provider>/<model-id>` notation (e.g., `github-copilot/gpt-4o`, `anthropic/claude-opus-4`, `ollama/llama3.3`) — same convention as OpenClaw for familiarity and potential interop\n"}}}} |