joyehuang/Learn-Open-Harness

Dual-Layer Pedagogical Runtime

The platform implements a bifurcated architecture separating didactic delivery (Next.js 14 App Router) from agent simulation (TypeScript harness runtime). This allows progressive hydration where theoretical chapters load as React Server Components while interactive sandboxes hydrate client-side with full agent-loop execution capabilities.

State Management Architecture

Employs Zustand for client-side tutorial progress and Web Workers for agent-loop isolation. The MemoryStore implements a tiered caching strategy: Ephemeral (current conversation), Working (chapter context), and Persistent (localStorage for user progress).

The platform pioneers 'Executable Pedagogy'—collapsing documentation and runtime into a single artifact where learning materials are simultaneously the execution environment, eliminating the friction between reading about agent loops and implementing them.

Architectural Innovations

1. Progressive Disclosure Engine: Implements a chapter-gating system where each of the 12 chapters unlocks specific APIs in the HarnessEngine. Chapter 1 exposes only agent.respond(); Chapter 8 exposes agent.useTool(); Chapter 12 exposes swarm.orchestrate(). This enforces conceptual scaffolding at the compiler level through TypeScript interface merging.
2. Claude Code Loop Simulation: Faithful implementation of the Read-Eval-Print-Agent (REPA) loop observed in Claude Code, utilizing async function* agentLoop() generators with yield checkpoints for observability. The LoopController class implements backpressure mechanisms to prevent runaway agent iterations.
3. Holographic Memory Visualization: Real-time DOM representation of the agent's ContextWindow using useEffect hooks that map token usage to visual 'memory pressure' indicators, teaching users about LLM context limitations through direct manipulation.
4. Tool Schema Injection: Dynamic Zod schema generation for tool definitions, allowing type-safe tool registration via ToolRegistry.register<T>(name: string, schema: ZodType<T>, handler: (input: T) => Promise<unknown>). This bridges the gap between TypeScript's static types and LLM function calling.
5. Multi-Agent Simulation Sandbox: WebRTC-based communication layer for Chapter 12's multi-agent scenarios, enabling browser-based distributed agent simulation without backend dependencies.

Educational Efficacy Metrics

Scalability Limitations

Current architecture faces constraints in the Web Worker heap limit (~2GB) for complex multi-agent simulations. The AgentSwarm implementation utilizes SharedArrayBuffer for inter-agent communication, requiring cross-origin isolation headers that complicate deployment on restrictive CDNs.

Competitive Positioning

Integration Architecture

• Deployment: Optimized for Vercel Edge Runtime with export const runtime = 'edge' for low-latency chapter delivery globally.
• Local Development: Docker Compose configuration mounting local LLM endpoints (Ollama) via OLLAMA_HOST environment variable for private agent execution.
• Migration Path: Tutorial code uses standard fetch patterns compatible with OpenAI, Anthropic, and local LLM APIs; HarnessEngine abstracts provider-specific implementations.

Production Adoption Patterns

Observed deployment in enterprise settings as internal agent literacy platforms, where organizations fork the repo and customize Chapters 3-6 to reflect internal tool APIs. The shadcn/ui theming system allows brand customization without touching core harness logic.