ZeroSpinner

The Preemptive Kernel & Circuit Breaker for Autonomous AI Agents.
Eliminate the infinite spinner. Intercept recursive over-refinement. Deliver the second milestones pass.

🚨 The Infinite Spinner Anti-Pattern

Modern autonomous AI coding agents (Claude Code, Antigravity, Devin, LangGraph, MetaGPT) frequently suffer from the Infinite Spinner Dilemma:

1. The Matryoshka Spawning Trap: A coordinator agent spawns a worker, which spawns an improvement agent, which spawns a reviewer, which spawns a linter. The human stares helplessly at a spinning UI loader while execution depth spirals out of control.

2. Speculative Over-Refinement: The core engineering goal (e.g. tests passed, PR created, build succeeded) was completed in 45 seconds. However, secondary improvement loops keep spinning for another 10 minutes performing speculative, microscopic polish that adds zero business value.

3. Blackbox Stall Deadlocks: Tool calls freeze on network hangs or process locks, while the terminal outputs nothing and leaves the operator guessing.

ZeroSpinner solves this by acting as a non-invasive preemptive kernel between the agent, the runtime process, and the human developer.

Related MCP server: Agent Bridge MCP

🌟 Key Capabilities

• 🎯 Preemptive Milestone Engine: Scans stdout streams and JSONL transcripts using high-speed heuristics for key milestones (MILESTONE_TESTS_PASSED, MILESTONE_PR_CREATED, MILESTONE_BUILD_SUCCESS, MILESTONE_COMMIT_PUSHED). Dispatches immediate notifications without waiting for the full multi-turn cycle to complete.

• 🛑 Anti-Matryoshka Circuit Breaker: Enforces strict subagent nesting depth (max_depth), token limits, and time budgets. When a core milestone is reached, speculative secondary polishers are intercepted immediately (TRIP_STOP_AND_DELIVER) with auto-termination of child processes.

• ⚡ Dual-Engine Resilient Router (Nebius Token Factory x NVIDIA Nemotron & DeepSeek-R1): Seamlessly dispatches reasoning queries between Nebius Token Factory (nvidia/Llama-3.1-Nemotron-70B-Instruct) and private Subsystem Beta (DeepSeek-R1-Distill-Qwen-32B-abliterated on Colab A100-80GB BF16) with zero-leakage automated failover.

• 🐕 Active Transcript Watchdog: Non-invasively tails JSONL transcripts and process streams to detect tool-call stalls and repetitive loop deadlocks.

• ⏱️ 60-Second Active Heartbeat Telemetry: Automatically aggregates and outputs a comprehensive telemetry status report every 60 seconds, displaying processing velocity (lines/min), intercepted speculative cycles, estimated token and dollar savings, circuit breaker health, and cloud microVM states.

• 🪟 Glassbox Terminal HUD: High-contrast, Rich-based terminal dashboard replacing the empty spinner with real-time agent hierarchy trees, milestone badges, telemetry gauges, and live activity streams.

• 🔌 Standard MCP Server: Native Model Context Protocol (MCP) server supporting both mcp 2.x and legacy FastMCP with complete boolean tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint).

🏛️ Dual-Engine Architecture

flowchart TD
    subgraph Agent Runtime
        A[Autonomous Agent / Coordinator] -->|Spawns Subagents| B[Child Workers]
        B -->|Executes Tools & Code| C[Stdout / Transcript Stream]
    end

    subgraph Dual-Engine Router
        DE[EngineRouter] -->|Primary Cloud Backend| N[Nebius Token Factory / NVIDIA Nemotron 70B]
        DE -->|Private Fallback Brain| DS[Subsystem Beta / Colab A100 DeepSeek-R1 32B]
        N -.->|Auto Fallback on Failure| DS
    end

    subgraph ZeroSpinner Kernel
        C -->|Active Non-invasive Tail| W[TranscriptWatchdog]
        C -->|Stream Sniffing| M[MilestoneDetector]
        M -->|Fast-Path Preemptive Event| CB[CircuitBreaker Governor]
        W -->|Stall / Loop Telemetry| CB
        CB -->|Anti-Matryoshka Depth Guard| A
        CB -->|Speculative Over-refinement Stop| B
        CB -->|Reasoning Dispatch| DE
    end

    subgraph User Experience
        M -->|Milestone Badges| HUD[Glassbox Terminal HUD]
        CB -->|Breaker State & Gauges| HUD
        W -->|Live Activity Stream| HUD
        CB -->|Preemptive Exit| D[Instant Human Delivery]
    end

🚀 Quickstart

1. Installation

# Clone and install in editable mode
git clone https://github.com/jdymitarai/zerospinner.git
cd zerospinner
pip install -e .

# Or with optional MCP server support
pip install -e ".[mcp]"

2. Interactive Simulation Demo

Experience how ZeroSpinner stops recursive subagent loops and triggers instant delivery:

zspin demo

(Add --fast for quick automated validation, or --headless for plain ASCII outputs).

3. Supervise Any Agent or Command

Wrap existing tools, tests, or agents with the Glassbox HUD and circuit breaker:

# Wrap a test run
zspin run -- pytest tests/

# Wrap an autonomous agent CLI with depth and time bounds
zspin run --max-depth 2 --time-budget 300 -- claude "Fix issue #42"

4. Watch an Active Agent Session

Tail an active JSONL transcript in real-time with full telemetry:

zspin watch ~/.claude/transcripts/session-latest.jsonl --poll 1.0

5. Neural Vulnerability & Memory-Safety Auditor (A100 DeepSeek-R1 / Nebius)

Audit complex C/C++ parser targets for remote heap exploits and integer overflows with native <think> mathematical proofs:

# Audit real-world target with Subsystem Beta (Colab A100-80GB BF16 DeepSeek-R1)
zspin audit tests/prp_tier1_parser.c --backend deepseek

# Or audit via Nebius Token Factory (NVIDIA Nemotron-70B)
zspin audit tests/prp_tier1_parser.c --backend nebius

🔌 Model Context Protocol (MCP) Integration

ZeroSpinner includes a standard FastMCP server that connects directly with Claude Desktop, Cursor, or Antigravity.

MCP Configuration (claude_desktop_config.json)

{
  "mcpServers": {
    "zerospinner": {
      "command": "zspin",
      "args": ["mcp"]
    }
  }
}

Exposed MCP Tools

🐍 Python SDK API Reference

Embed ZeroSpinner directly inside your custom agentic pipelines (LangGraph, AutoGen, CrewAI):

from zerospinner.core import (
    MilestoneDetector,
    CircuitBreaker,
    MILESTONE_TESTS_PASSED,
    MILESTONE_PR_CREATED,
)

# 1. Initialize Kernel Components
detector = MilestoneDetector()
breaker = CircuitBreaker(
    max_depth=2,                 # Disallow subagents beyond depth 2
    time_budget_sec=300.0,       # Max 5 minutes total
    stop_on_core_milestone=True, # Preempt speculative polish once tests/PR pass
)

# Auto-wire detector to breaker
detector.on_milestone(breaker.record_milestone)

# 2. Fast-Path Preemptive Notification Callback
detector.on_milestone(lambda event: print(f"?FAST-PATH ALERT: {event.milestone_type}"))

# 3. Supervise Subagent Spawns
allowed, err = breaker.register_subagent(
    agent_id="subagent-42",
    parent_id="root-coord",
    role="coding_worker",
)
if not allowed:
    print(f"Governor Intercepted: {err}")

# 4. Feed Output Chunks
detector.scan_chunk("================= 24 passed in 0.81s =================")

# 5. Check Breaker State
if breaker.is_tripped():
    print(f"Breaker tripped: {breaker.trip_reason} -> Deliver immediately!")

🧪 Comprehensive Verification Suite

Run the full unit and integration test suite:

pytest tests/ -v

All 36 tests cover:

• Pytest, Cargo, Jest, Go, and Python unittest regex matching

• Fast-path preemptive callback dispatch and exception isolation

• Transcript tailing and partial JSON buffer assembly

• Tool-call stall timeouts and repetitive loop deadlocks

• Anti-Matryoshka depth limiting and speculative over-refinement trips

• Child process termination under Windows (taskkill) and POSIX (SIGTERM)

• Rich Glassbox HUD rendering and MCP tool invocations

📄 License

ZeroSpinner is licensed under the MIT License.