feat: add Assistive SDK with cyberloop() wrapper and middleware system (v2.2)

Introduce a lightweight alternative to the Orchestrator that wraps
existing agents with composable middleware. The SDK instruments the
inner loop (budget, policy, kinematics, telemetry) while leaving
outer-loop orchestration to user code.

Core changes:
- Agent protocols: AgentLike (opaque) and SteppableAgent (step-level)
- cyberloop(agent, opts) wrapper with automatic agent type detection
- Middleware system: runner, budget, telemetry, stagnation, probe, evaluator
- policyMiddleware: declarative ChainPolicy wiring with decideAction()
- kinematicsMiddleware: EKF/PID drift detection as middleware
- Adapter decoupling: domain adapters no longer import core directly

Examples:
- quickstart, middleware-demo, openai-agents-demo (new)
- GitHub and Wikipedia demos ported to SDK alongside legacy versions

Documentation:
- docs/guide/choosing-your-api.md (new — SDK vs Orchestrator guide)
- ADR-0002: Assistive SDK architectural decision record
- Updated README, EVOLUTION, COMPONENT_INTERACTIONS, GLOSSARY,
  TESTING_GUIDE, AICL, TECHNICAL_SPEC_v2.1, inner-outer-loop

Author: roackb2

README.md

@@ -26,6 +26,34 @@ CyberLoop (Blue) dampens this oscillation through closed-loop feedback.</em>
 
 In **v2.1**, we introduce **Semantic Kinematics**: giving agents a "vestibular system" (inner ear) to detect drift in vector space without needing to "think" (query an LLM). This allows agents to navigate complex knowledge graphs using **pure mathematics**—making them 100x faster and cheaper than traditional Chain-of-Thought agents.
 
+In **v2.2**, we refactor the developer surface into a lightweight **Assistive SDK**. Instead of building inside the framework (`Orchestrator` + 7 interfaces), you now wrap your existing agent with `cyberloop(agent)` and progressively opt into middleware. The Orchestrator is preserved for backward compatibility.
+
+---
+
+## ⚡ Quick Start: The SDK (v2.2)
+
+```typescript
+import { cyberloop } from 'cyberloop'
+
+// Tier 1: Wrap any agent — get budget control for free
+const controlled = cyberloop(myAgent, { budget: { maxSteps: 20 } })
+const result = await controlled.run('your query')
+
+// Tier 2: Expose step-level control for middleware
+const controlled = cyberloop(mySteppableAgent, {
+  budget: { maxSteps: 50 },
+  middleware: [telemetryMiddleware(logger), stagnationMiddleware()],
+})
+
+// Tier 3: Advanced — add kinematics (EKF/PID drift detection)
+import { kinematicsMiddleware } from 'cyberloop/advanced'
+const controlled = cyberloop(mySteppableAgent, {
+  middleware: [kinematicsMiddleware({ embedder, goalEmbedding, ... })],
+})
+```
+
+See [examples/quickstart.ts](src/examples/quickstart.ts) for a runnable 30-line demo.
+
 ---
 
 ## 🚀 Hero Demo: Project Ariadne
@@ -41,7 +69,11 @@ Using CyberLoop v2.1, the agent navigates Wikipedia using only **Embeddings + PI
 yarn install
 
 # 2. Run the Deep-Dive Scenario (Coffee -> French Revolution)
-yarn examples:wikipedia revolution
+# v2.2 SDK version (cyberloop wrapper + middleware):
+yarn examples:wikipedia:cyberloop -- --scenario revolution
+
+# Legacy Orchestrator version (all benchmark modes):
+yarn examples:wikipedia -- --mode cyberloop --scenario revolution
 
 ```
 
@@ -84,6 +116,26 @@ The strategic system that handles planning, replanning, and final evaluation.
 * **Trigger:** Only activated when the Inner Loop budget is exhausted or a stable state is found.
 * **Cost:** Expensive, but rarely invoked.
 
+### 3. Developer API: Three Tiers (v2.2)
+
+The SDK exposes the control loop at three levels of granularity:
+
+| Tier | API | You Provide | CyberLoop Adds | Example |
+| --- | --- | --- | --- | --- |
+| **1. Opaque** | `cyberloop(agent)` | Any agent with `run()` | Budget, event hooks | [quickstart.ts](src/examples/quickstart.ts) |
+| **2. Steppable** | `cyberloop(steppableAgent)` | Agent with `step()`, `isDone()` | Per-step middleware (telemetry, stagnation, policy) | [middleware-demo.ts](src/examples/middleware-demo.ts) |
+| **3. Advanced** | `+ kinematicsMiddleware()` | Embedder + goal vector | EKF/PID drift detection | [demo-cyberloop.ts](src/examples/wikipedia/demo-cyberloop.ts) |
+
+The legacy `Orchestrator` API remains available for full inner/outer loop control.
+
+### 📖 Which API Should I Use?
+
+**SDK (`cyberloop()`)** — You own the outer loop. CyberLoop instruments the inner loop with composable middleware (budget, policy, kinematics, telemetry). Best for adding control to existing agents or custom orchestration topologies.
+
+**Orchestrator** — CyberLoop owns the full plan → explore → evaluate → replan cycle. Best for research prototyping and reproducing paper benchmarks.
+
+👉 **[Full comparison and decision guide →](docs/guide/choosing-your-api.md)**
+
 ---
 
 ## 📉 Industrial Validation (Legacy)
@@ -127,29 +179,40 @@ OPENAI_API_KEY=sk-...
 ### Available Demos
 
 ```bash
-# v2.1: Wikipedia Deep-Dive (Semantic Kinematics)
-# Scenarios: 'tech' (Jacquard -> CPU) or 'revolution' (Coffee -> French Revolution)
-yarn examples:wikipedia revolution
-
-# v1.0: GitHub Search (Deterministic State Machine)
-# A classic example of bounded exploration using Probes & Ladders
-yarn examples:github
+# --- SDK Examples (v2.2) ---
+yarn examples:quickstart                          # Tier 1: opaque agent
+yarn examples:middleware                           # Tier 2: steppable + custom middleware
+yarn examples:openai-agents                        # OpenAI Agents SDK compatibility
+
+# --- Wikipedia Navigation (v2.1 Semantic Kinematics) ---
+yarn examples:wikipedia:cyberloop                  # SDK version (cyberloop wrapper)
+yarn examples:wikipedia:cyberloop -- --scenario revolution
+yarn examples:wikipedia                            # Legacy Orchestrator (all modes)
+
+# --- GitHub Search (v1.0 Deterministic State Machine) ---
+yarn examples:github:cyberloop                     # SDK version (steppable agent)
+yarn examples:github:baseline:cyberloop            # SDK version (OpenAI Agent)
+yarn examples:github                               # Legacy Orchestrator
+yarn examples:github:baseline                      # Legacy baseline
 
 ```
 
 ---
 
 ## 📂 Documentation
 
+* **Guide:** [Choosing Your API — SDK vs Orchestrator](docs/guide/choosing-your-api.md)
 * **Benchmarks:** [Wikipedia Navigation Results](docs/benchmarks/wikipedia/benchmark-wikipedia-navigation.md)
 * **Theory:** [AICL Whitepaper](docs/whitepaper/AICL.md)
+* **Philosophy:** [Immutable Principles](docs/whitepaper/PHILOSOPHY.md)
+* **Evolution:** [Why the architecture changed](docs/whitepaper/EVOLUTION.md)
 * **Architecture:** [Inner/Outer Loop Spec](docs/architecture/inner-outer-loop.md)
 * **Academic (v2.1):** Zenodo Record - [The Brain Needs a Body (Liang, 2026)](https://zenodo.org/records/18138161)
 * **Academic (v1.0):** Zenodo Record - [AICL Whitepaper (Liang, 2025)](https://zenodo.org/records/17835680)
 
 ---
 
-> **Status:** 🧪 *v2.1 Research Preview*
+> **Status:** 🧪 *v2.2 Assistive SDK*
 > Uncontrolled intelligence grows powerful but fragile.
 > Controlled intelligence grows stable — and endures.
 

docs/adr/0001-inner-outer-loop-architecture.md

@@ -25,6 +25,7 @@ Output
 ```
 
 **Characteristics:**
+
 - Multiple policies with dynamic routing
 - Failure classification for policy selection
 - Complex termination logic
@@ -98,6 +99,7 @@ Final Output
 ### Preserved Interfaces (For Future Extension)
 
 We keep but don't use:
+
 - `StrategySelector` - For multi-domain agents requiring policy routing
 - `FailureClassifier` - For complex failure modes (distributed systems, bug triage)
 - `TerminationPolicy` - For multi-objective optimization
@@ -137,13 +139,15 @@ Total: ??? (hard to predict)
 #### 3. **Simplicity for Common Cases**
 
 For single-domain tasks (GitHub search, API discovery):
+
 - **No routing overhead** - Direct ProbePolicy execution
 - **No classification overhead** - Direct state examination
 - **Clear decision flow** - Plan → Explore → Evaluate
 
 #### 4. **Extensibility for Complex Cases**
 
 For multi-domain tasks (bug localization, distributed system triage):
+
 - **Interfaces preserved** - Can add StrategySelector when needed
 - **Clear extension points** - Add FailureClassifier for complex diagnosis
 - **Documented migration path** - See unused-interfaces.md
@@ -191,6 +195,7 @@ From our GitHub search benchmark:
 ### Current Status (v0.1.0)
 
 **Implemented:**
+
 - ✅ Orchestrator with inner/outer loop separation
 - ✅ ProbePolicy interface with initialize/decide/isStable
 - ✅ Planner interface with plan/evaluate/replan
@@ -199,6 +204,7 @@ From our GitHub search benchmark:
 - ✅ Benchmark comparing to baseline
 
 **Not yet implemented:**
+
 - ⚠️ Beam search (parallel candidates)
 - ⚠️ Query memoization and deduplication
 - ⚠️ Adaptive thresholds (EMA-based)
@@ -214,6 +220,7 @@ Based on feedback from GPT discussion, these optimizations will address the spee
 **Problem:** Sequential exploration is slow (5 API calls)
 
 **Solution:** Parallel candidates with OR merging
+
 ```typescript
 // Instead of:
 t=0: try "node graceful shutdown" → 106 hits
@@ -233,6 +240,7 @@ t=0: try ["node graceful shutdown", "node AND graceful AND shutdown", "graceful
 **Problem:** Oscillation between same queries (106 → 7 → 106)
 
 **Solution:** Cache and detect duplicates
+
 ```typescript
 // Normalize query
 const key = normalize({ keywords, minStars, language })
@@ -253,6 +261,7 @@ if (seenHashes.has(resultHash)) {
 **Problem:** Hard-coded thresholds (10-30 hits) don't work for all queries
 
 **Solution:** Learn thresholds dynamically
+
 ```typescript
 // Instead of:
 if (hits >= 10 && hits <= 30) return stable
@@ -270,6 +279,7 @@ if (variance < threshold && hits > minAcceptable) return stable
 **Problem:** Inner/outer loops don't coordinate on budget
 
 **Solution:** Link budgets
+
 ```typescript
 // When outer loop budget low:
 if (outerBudget.remaining() < 1.0) {
@@ -289,8 +299,9 @@ if (noImprovementSteps > 5) {
 **Problem:** Only measuring quantity (10 repos vs 3), not quality
 
 **Solution:** Composite score
+
 ```typescript
-score = 
+score =
   0.4 * qualityScore(stars, description) +
   0.3 * freshnessScore(lastUpdate) +
   0.2 * licenseScore(license) +
@@ -302,13 +313,15 @@ score =
 ### Integration with Orchestrator
 
 **Current:** Manual outer loop calls
+
 ```typescript
 const state = await planner.plan(input)
 const result = await orchestrator.exploreInnerLoop(state)
 const output = await planner.evaluate(result.state)
 ```
 
 **Recommended:** Integrated `runAdaptive()`
+
 ```typescript
 const result = await orchestrator.runAdaptive({
   userInput,
@@ -380,7 +393,7 @@ See [docs/use-cases.md](../use-cases.md) for detailed scenarios.
 
 ---
 
-**Decision made by:** Framework authors  
-**Date:** 2025-10-11  
-**Supersedes:** Initial AICL routing-based design  
-**Superseded by:** None (current)
+**Decision made by:** Framework authors
+**Date:** 2025-10-11
+**Supersedes:** Initial AICL routing-based design
+**Superseded by:** None (current; extended by [ADR-0002](0002-assistive-sdk-cyberloop-wrapper.md))